GET /apiv2/compliance/

Consulta de conformidade aberta e sem chave para um único endereço TRON. Ela retorna um veredito — se o endereço está bloqueado e em qual categoria — fornecido inteiramente a partir de um cache de lista de negação em memória. Sem chave de API, sem saldo, sem cobrança. O objetivo é permitir que qualquer pessoa integre a camada de conformidade com uma única requisição HTTP GET.

O endpoint lê apenas um cache, nunca o banco de dados ou um nó da blockchain, portanto uma consulta leva uma fração de milissegundo. O limite de requisições é aplicado por IP pelo gateway.

URL do endpoint

GET https://netts.io/apiv2/compliance/{address}

Nenhum cabeçalho de autenticação é necessário.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
address	string	Sim	Endereço base58 da TRON — T seguido de 33 caracteres

Exemplos de Requisições

cURL

curl https://netts.io/apiv2/compliance/TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL

Python

import requests

address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL"
r = requests.get(f"https://netts.io/apiv2/compliance/{address}")
data = r.json()

if r.status_code == 200:
    d = data["data"]
    print(f"blocked : {d['blocked']}")
    print(f"category: {d['category']}")
    if d["category"] == "aml_risk":
        print(f"reason  : {d.get('reason_code')} — {d.get('label')}")
else:
    print(f"Error: {data}")

JavaScript

const address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL";
const res = await fetch(`https://netts.io/apiv2/compliance/${address}`);
const { data } = await res.json();
console.log(data.blocked, data.category, data.label);

Resposta

Bloqueado — na lista de negação central (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL",
        "blocked": true,
        "category": "aml_risk",
        "severity": "BLOCK",
        "reason_code": "SANCTIONS_SCREENING",
        "label": "DPRK Bitget Exploit - September 2026",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": ["aml_risk"],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Carteira GasFree — um contrato inteligente que pode receber USDT (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TZEMF5vmSABaWjeUPty8kFpUsquMAKhGFp",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "gasfree_wallet",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T12:00:00+00:00"
    }
}

Contrato excluído — o endereço ainda conta como um contrato inteligente (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TBtrogXC58EAvE7vod56ZnzRY4y5jrwtbN",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "selfdestructed_contract",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

Limpo — em nenhum dos conjuntos (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC",
        "blocked": false,
        "category": "clean",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": [],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Campos da Resposta

Campo	Tipo	Descrição
data.address	string	O endereço que foi verificado
data.blocked	boolean	true se o endereço estiver em qualquer conjunto de bloqueio
data.category	string	aml_risk, usdt_frozen, smart_contract, spam_sender ou clean (veja abaixo); o endpoint em lote também pode retornar invalid ou unavailable
data.severity	string	Apenas para aml_risk. Ex.: BLOCK, REVIEW
data.reason_code	string	Apenas para aml_risk. Código de máquina, ex.: SANCTIONS_OFAC_SDN
data.label	string	Apenas para aml_risk. Rótulo legível para humanos
data.subtype	string | null	Refina smart_contract. gasfree_wallet — uma carteira GasFree ativa (veja Carteiras GasFree); selfdestructed_contract — o contrato neste endereço foi excluído (veja Contratos excluídos); null caso contrário
data.subtype_status	string	confirmed — o subtipo é conhecido pelo estado confirmado mais recente; not_found — nenhum dos subtipos se aplica; unavailable — uma lista de subtipos não pôde ser consultada no momento, então subtype é null e não afirma nada
data.matches	string[]	Todos os conjuntos em que o endereço está presente, em ordem de prioridade (ex.: ["usdt_frozen", "smart_contract", "spam_sender"]). category é apenas o primeiro deles
data.checks_complete	boolean	true se todos os quatro conjuntos estavam carregados e atualizados no momento da consulta. false significa que uma resposta clean se baseia em uma verificação incompleta
data.checked_at	string	Timestamp UTC ISO-8601 da consulta

Categorias

category é um veredito, não uma pontuação de risco. Quando um endereço está em mais de um conjunto, a categoria mais grave prevalece, nesta ordem (todas elas são listadas em matches):

Categoria	blocked	Significado
aml_risk	true	Na lista de negação central: sanções, golpes, ransomware, ativos roubados, fraude, conclusões de autoridades policiais ou de abuso interno. Um motivo com curadoria é anexado
usdt_frozen	true	O endereço foi congelado pelo emissor do USDT (Tether). Ele não pode movimentar USDT, portanto a delegação de recursos para ele é recusada
smart_contract	true	Um endereço de contrato inteligente conhecido, incluindo contratos excluídos posteriormente. Veja a nota abaixo
spam_sender	true	Remetente confirmado de spam em massa
clean	false	Em nenhum dos conjuntos
unavailable	null	A lista de negação central não pôde ser consultada, portanto o endereço não está confirmado como limpo nem como bloqueado. Apenas em lote; o endpoint de endereço único retorna 503 com code 5004 em vez disso. Veja Lista de negação central indisponível

Contratos inteligentes são bloqueados por um motivo técnico, não de AML

Um veredito smart_contract significa que o endereço pertence a um contrato, não a uma carteira de usuário, portanto a Energy não é delegada a ele e o endereço é recusado antes mesmo de um pedido ser realizado. O conjunto contém todos os endereços onde um contrato foi criado com sucesso, incluindo contratos que foram excluídos posteriormente — um contrato excluído não transforma seu endereço em uma carteira de usuário. Isso não significa que o contrato esteja comprometido, contaminado ou seja de alto risco sob AML. A maioria dos contratos neste conjunto é perfeitamente comum. Trate smart_contract como "não é um destino para delegação", não como um alerta de risco.

Carteiras GasFree

Uma carteira GasFree é um contrato que permite ao seu proprietário receber e enviar tokens e pagar a taxa de rede nesses mesmos tokens. Cada uma é criada pelo controlador GasFree TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U. Esse endereço é reportado como category: "smart_contract" com subtype: "gasfree_wallet".

A diferença é importante ao rotear fundos:

	Contrato inteligente comum	Carteira GasFree
Enviar USDT para ele	não é um destinatário normal	sim — é a carteira de um usuário
Delegar Energy para ele	não	não — não delegamos Energy para carteiras GasFree
category / subtype	smart_contract / null	smart_contract / gasfree_wallet

Cobertura e advertências:

• Apenas carteiras implantadas são conhecidas. Um endereço GasFree que recebeu USDT, mas nunca enviou nada, ainda não foi implantado, portanto não está em nenhum conjunto e retorna como clean.
• O subtipo descreve onde o endereço pode receber fundos. Ele não diz nada sobre transferências originadas de uma carteira GasFree; faça a triagem do endereço remetente separadamente.
• subtype_status: "unavailable" significa que a lista GasFree não pôde ser consultada. O restante do veredito (blocked, category, matches) continua válido.
• O próprio controlador e outros contratos não são carteiras GasFree: eles retornam com subtype: null.

Contratos excluídos

Um contrato pode excluir a si mesmo (autodestruição). O endereço permanece no conjunto smart_contract: ele era um endereço de contrato, não uma carteira de usuário, e a Netts não delega recursos nem envia pagamentos para ele. Esse endereço é reportado como category: "smart_contract" com subtype: "selfdestructed_contract".

• confirmed significa excluído de acordo com o estado mais recente confirmado por um nó TRON. Não é uma garantia sobre o futuro: um contrato pode ser implantado novamente no mesmo endereço e, então, o subtipo é removido enquanto o endereço continua como smart_contract.
• Uma chamada de autodestruição por si só não significa exclusão: na TRON, um contrato criado em uma transação anterior mantém seu código após ela. Apenas o estado do nó conta.
• Se um endereço for tanto um contrato excluído quanto estiver em uma lista GasFree, selfdestructed_contract prevalece — o endereço não é reportado como uma carteira GasFree funcional.
• subtype_status: "unavailable" significa que a lista de contratos excluídos não pôde ser consultada; o restante do veredito continua válido e nenhum endereço é confirmado como uma carteira GasFree até que ela possa ser consultada novamente.

Códigos de motivo e o provedor de dados

Para aml_risk, o reason_code e o label descrevem por que o endereço está listado. Autoridades públicas de sanções são mantidas como estão — SANCTIONS_OFAC_SDN, SANCTIONS_EU_FSF, SANCTIONS_UK_FCDO e assim por diante. O nome do provedor comercial de triagem por trás de uma conclusão nunca é exposto: esses códigos são normalizados para SANCTIONS_SCREENING, e qualquer nome de provedor é removido de label.

Tamanho da lista de negação

GET https://netts.io/apiv2/compliance/stats

Tamanhos agregados dos conjuntos por trás do veredito, a partir do mesmo cache. Aberto e sem chave.

{
    "code": 0,
    "status": "ok",
    "data": {
        "aml_risk": 1079,
        "usdt_frozen": 8022,
        "smart_contract": 7581686,
        "spam_sender": 27039018,
        "gasfree_wallets_subset": 512487,
        "selfdestructed_contracts_subset": 4065766,
        "total": 34629805,
        "revision": 1117,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

smart_contract é a maior parte neutra em AML do total — veja a nota sobre contratos acima. gasfree_wallets_subset (carteiras GasFree ativas) e selfdestructed_contracts_subset (contratos excluídos) são partes de smart_contract; eles não são somados ao total. Se um desses dois contadores não puder ser lido no momento, ele será null e os outros números ainda serão retornados.

Consulta em lote (chave de API)

Para verificar muitos endereços de uma só vez, use o endpoint em lote autenticado. Ele existe para economizar viagens de ida e volta na rede: uma única requisição e um único pipeline interno em vez de N GETs separados. Um único endereço é apenas um array de um elemento.

POST https://netts.io/apiv2/compliance/batch
x-api-key: YOUR_KEY
Content-Type: application/json

{ "addresses": ["TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC"] }

Até 1000 endereços por requisição. Os vereditos retornam na mesma ordem, cada um com os mesmos campos da resposta de endereço único (incluindo subtype, subtype_status, matches e checks_complete), além de category: "invalid" (com um campo error) para qualquer entrada malformada — uma entrada inválida não falha o lote inteiro. Se a lista de negação central não estiver carregada, um endereço que de outra forma estaria limpo retorna como category: "unavailable" (blocked: null, com um campo error) em vez de clean — veja Lista de negação central indisponível.

{
    "code": 0,
    "status": "ok",
    "data": {
        "count": 2,
        "checked_at": "2026-09-27T12:00:00+00:00",
        "results": [
            { "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "blocked": true, "category": "aml_risk", "subtype": null, "subtype_status": "not_found", "matches": ["aml_risk"], "checks_complete": true, "severity": "BLOCK", "reason_code": "SANCTIONS_SCREENING", "label": "DPRK Bitget Exploit - September 2026" },
            { "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC", "blocked": false, "category": "clean", "subtype": null, "subtype_status": "not_found", "matches": [], "checks_complete": true }
        ]
    }
}

O endpoint em lote requer uma chave de API (cabeçalho x-api-key) e a chave pode opcionalmente ser vinculada a uma lista de permissões de IP. Entre em contato conosco para obter uma chave.

Seu limite de requisições é por chave e mais alto do que o endpoint público de endereço único:

Período	Limite
1 segundo	200 requisições
1 minuto	12.000 requisições

Cada requisição pode conter até 1000 endereços, de modo que uma única chave pode analisar bem mais de cem mil endereços por segundo dentro deste limite.

Respostas de Erro

Formato de endereço inválido (400)

{
    "code": 1001,
    "status": "error",
    "msg": "Invalid TRON address format (expected base58, 'T' + 33 chars)"
}

Serviço temporariamente indisponível (503)

{
    "code": 5003,
    "status": "error",
    "msg": "compliance service temporarily unavailable"
}

Lista de negação central indisponível (503, código 5004)

O veredito é fornecido a partir de um cache em memória. Se esse cache estiver acessível, mas a lista de negação central de AML não estiver carregada no momento, ou sua revisão atual falhar em uma verificação de integridade, o endpoint não faz fallback para clean — isso reportaria um endereço não verificado como seguro. Em vez disso, ele informa claramente que não pôde produzir um veredito:

{
    "code": 5004,
    "status": "error",
    "msg": "compliance deny-list temporarily unavailable, verdict cannot be produced"
}

O que isso significa: o endereço não está confirmado como limpo nem como bloqueado. O serviço não pôde compará-lo com a lista de sanções/AML neste momento. Não trate o endereço como limpo — tente novamente em breve.

Um bloqueio definitivo ainda é retornado normalmente: se o endereço for correspondente a USDT congelado, contrato inteligente ou remetente de spam (conjuntos que não dependem da lista central), você recebe o veredito habitual blocked: true mesmo neste estado. Apenas uma resposta que seria clean torna-se 5004.

No endpoint em lote, a mesma situação é reportada por endereço como category: "unavailable" (blocked: null, com um campo error); o restante do lote não é afetado. Este é um estado raro e transitório.

Registro indisponível (503, código 5005)

Os conjuntos são atualizados no local e permanecem legíveis enquanto são atualizados, de modo que uma atualização de rotina nunca afeta o veredito. Apenas se a aplicação de um conjunto tiver falhado é que um endereço que de outra forma estaria limpo não poderá ser confirmado como limpo. O endpoint de endereço único então retorna:

{
    "code": 5005,
    "status": "error",
    "msg": "address registry temporarily unavailable, verdict cannot be produced, retry shortly"
}

Assim como no 5004, um bloqueio definitivo ainda é retornado normalmente, e o endpoint em lote reporta o caso por endereço como category: "unavailable". Tente novamente mais tarde.

Referência de Códigos de Erro

Código	Descrição	Status HTTP
0	Sucesso	200
1001	Formato de endereço TRON inválido	400
5003	Backend de cache temporariamente indisponível	503
5004	Lista de negação central não carregada — o veredito não pode ser produzido (tente novamente)	503
5005	Falha ao aplicar um conjunto — o veredito não pode ser produzido (tente novamente)	503

Limites de Requisições

Existem dois níveis, aplicados no gateway:

Endpoint	Autenticação	Limitado por	1 segundo	1 minuto
GET /apiv2/compliance/{address}	aberta, sem chave	IP	10	300
GET /apiv2/compliance/stats	aberta, sem chave	IP	10	300
POST /apiv2/compliance/batch	chave de API	chave	200	12.000

O endpoint público de endereço único destina-se ao uso interativo e programático leve. Para triagem em massa, use o endpoint em lote: com até 1000 endereços por requisição e 200 requisições/segundo por chave, uma única chave analisa bem mais de cem mil endereços por segundo. Precisa de mais? O limite por chave é uma definição de política, não um teto técnico — entre em contato conosco.

Limite de Requisições Excedido (429)

{
    "message": "API rate limit exceeded"
}

Notas

• Sem autenticação e sem custo. Qualquer pessoa pode chamá-lo; não há nada para assinar.
• Apenas em cache. O veredito nunca consulta o banco de dados ou um nó, portanto é rápido e seguro para realizar consultas frequentes dentro do limite de requisições.
• Não é um relatório completo de AML. Para uma pontuação de risco, detalhamento de exposição e um relatório assinado, use a API de triagem autenticada (POST /apiv2/screening). Este endpoint responde a uma pergunta mais restrita: o endereço está na nossa lista de negação e por quê.