Risco de carteira cripto na API de Contas

Esta jornada usa a API de Contas (secureapi.<domínio>/api/v2) para consultar o risco de uma carteira cripto (Ethereum ou Tron) e obter um snapshot fechado com scores e resumos de eventos.

O contrato público é /crypto-risk/* no prefixo /api/v2 da API de Contas.

Referência OpenAPI: API de Contas — CryptoRisk.

Quando usar

Use esta API quando a sua aplicação precisa:

1. Pedir uma análise de risco de uma carteira (POST /crypto-risk/analyses)
2. Acompanhar a ingestão do histórico quando a carteira ainda não foi indexada (GET /crypto-risk/ingest)
3. Ler o snapshot fechado (GET /crypto-risk/analyses/{id})
4. Listar as análises já fechadas da conta (GET /crypto-risk/analyses)

O que não entra neste contrato: features snapshot, grafo de exposição, PDF, sanctions, indexer e rotas de staff.

Pré-requisitos

• mTLS configurado. Veja certificado mTLS.
• Credencial da API de Contas (Finance ou AppMobile) com os escopos crypto-risk.read e crypto-risk.write. No Finance: Configurações → API Contas → Nova credencial.
• Token OAuth. Veja Autenticação.

Credenciais já emitidas não recebem os novos escopos automaticamente. Crie uma nova credencial ou atualize a existente incluindo crypto-risk.read e crypto-risk.write.

Credencial BaaS (clientId com prefixo baas_) opera contas filhas. Envie x-account-id com o id interno da conta alvo. Credencial de conta opera a própria conta e não precisa do cabeçalho.

Redes

network	Suportada
ETHEREUM	Sim
TRON	Sim
BITCOIN, TRX ou qualquer outra	Não. Responde 422 antes de qualquer chamada upstream.

Body do POST: { "network": "ETHEREUM" | "TRON", "address": "..." }. Sem accountId no body.

Fluxo 201 vs 202

O POST /crypto-risk/analyses não faz poll interno. A primeira consulta de uma carteira nova pode devolver 202 imediatamente.

1. POST /crypto-risk/analyses { network, address }
2a. 201 → snapshot fechado (histórico já ingerido). Use o id.
2b. 202 → ingestão desta carteira começou ou ainda está rodando.
    Não há analysis id no 202.
3. Poll GET /crypto-risk/ingest?network=&address=
   até status=IDLE e persisted != null
4. Repita o POST → 201

Regras do 202:

• Retry do POST enquanto o ingest desta carteira está RUNNING também devolve 202.
• Ingest de outra carteira em andamento devolve 409.
• O body do 202 é { data: { status: "ACCEPTED", network, address, maxTransactions, ingest } }. Sem id de análise.

persisted = 0 com status = IDLE é índice vazio válido. Não trate como erro. Nesse caso, o POST seguinte devolve 201 com um snapshot de ingest vazio.

Ingest vazio não é carteira limpa

Risk 0 + baixa confiança + historyCovered=false é ingest vazio, não carteira limpa.

Isso acontece quando o índice da carteira existe, mas não há histórico coberto (incluindo 0 transações persistidas). Os scores passam como o CryptoRisk devolve. Não interprete riskScore = 0 sozinho como wallet “clean”.

Use historyCovered e confidenceScore juntos com riskScore e riskLevel antes de tomar decisão.

Snapshot fechado

O 201 e o GET /crypto-risk/analyses/{id} devolvem { data } com:

Campo	Significado
id	Identificador da análise
network, address	Carteira analisada
status	Status da análise (ex.: COMPLETED)
riskScore, riskLevel	Score e nível agregados
reputationScore, confidenceScore	Reputação e confiança
knownRiskScore, exposureRiskScore, behavioralRiskScore, anomalyRiskScore	Componentes
hardStop, hardStopRule	Interrupção por regra
historyCovered	Se o histórico foi coberto
scoringModelVersion, rulesVersion, featureVersion	Versões do modelo
startedAt, completedAt, createdAt	Timestamps
events[]	Resumos (eventType, component, severity, riskPoints, hopDistance, status, detectedAt)

Os events não incluem hash da transação nem endereço de contraparte. A listagem (GET /crypto-risk/analyses) devolve os mesmos campos sem events.

Análise de outra conta responde 404.

Listagem

GET /crypto-risk/analyses aceita network, address, page (padrão 1) e limit (padrão 20, máximo 100). Filtro de address exige network.

Resposta: { meta: { total, page, limit }, data }.

Erros

Os endpoints /crypto-risk/* respondem no envelope da API de Contas:

{
  "detail": "network must be ETHEREUM or TRON. Received: BITCOIN. BITCOIN and other networks are not supported.",
  "title": "Unprocessable entity",
  "type": "onz-0026",
  "instance": "/api/v2/crypto-risk/analyses"
}

HTTP	Quando
400	Body ou query inválidos (ex.: address sem network na listagem; id não numérico)
401	Token inválido ou escopo ausente
403	Acesso negado
404	Análise inexistente ou de outra conta
409	Ingestão de outra carteira em andamento
422	Rede não suportada (BITCOIN, TRX ou outra)
503	CryptoRisk indisponível ou falha upstream