POST /vasp/screenings

Recomendação de risco para transação em tempo real (KYT)

Submete uma transação pré ou pós-broadcast e recebe a recomendação síncrona ALLOW, REVIEW, HOLD ou DENY, com score de risco, sanções, regras disparadas e sinais internos de possível aplicabilidade. DENY somente com base em sanção (contraparte em lista de sanções ou com categoria de sanção) ou por regra de bloqueio que a própria empresa configurou no painel. Os demais riscos (misturador, darknet, valor, velocidade e outros) saem REVIEW, com risk_level preservado e o motivo do rebaixamento em reasons. Exceção: quando a empresa escolhe, no painel, bloquear automaticamente a proibição legal do misturador (Res. BCB nº 520/2025, art. 90, III, e parágrafo único), a contraparte misturador sai DENY com o motivo “política do cliente: proibição legal misturador” em reasons. Sem essa escolha, que por padrão fica desligada, ela segue REVIEW com o rótulo da proibição. A recomendação é análise auxiliar. A decisão operacional e o desfecho de suspeição pertencem ao cliente e são registrados em client_decision. Os campos legados em obligations não confirmam obrigação, envio ou homologação de Travel Rule, COAF ou DeCripto. Evidência necessária indisponível ou incompleta (contraparte não triável, provedor indisponível, timeout ou resposta incompleta) conclui a análise em HOLD: HTTP 200, fail_closed: true e o motivo em reasons, com a orientação de reprocessar com a mesma Idempotency-Key. HOLD é retenção temporária, não bloqueio, e nunca vira ALLOW; DENY por sanção ou regra do cliente prevalece sobre ele. Sem resultado do motor, ou com falha de persistência, auditoria ou infraestrutura, a rota responde 503 e nada é registrado nem cobrado. Replay idempotente via header Idempotency-Key.

customer_id (opcional) identifica a matrícula do titular na empresa autenticado: é o id UUID devolvido por POST /vasp/customers, com a mesma semântica do customer_id de POST /vasp/wallets. Quando enviado, toda resposta de sucesso inclui customer_id e holder_resolution, mesmo com o cruzamento desligado. RESOLVED informa que a matrícula pertence aa empresa; não afirma enriquecimento nem triagem negativa. NOT_FOUND cobre UUID desconhecido ou de outro empresa, sem alterar score, recomendação ou cobrança, e as regras que dependem do titular ficam fora da avaliação. Com o cruzamento desligado, nenhuma fonte declarada ou de KYC é consultada; somente as fontes autorizadas pelo contrato podem contribuir para a análise. Os sinais cruzados seguem a regra de DENY desta operação: só sanção, ou a política de bloqueio da própria empresa, bloqueia. Sem customer_id, holder_resolution e customer_id não vêm na resposta.

customer_id inválido (vazio, nulo, UUID zero, fora do formato canônico ou de outro tipo) responde 422 KYT_CUSTOMER_ID_INVALID, e a análise não roda. Falha de contrato ou de fonte do titular responde 503 KYT_HOLDER_UNAVAILABLE antes da análise, sem registro nem cobrança. A repetição idempotente conserva a resolução registrada no snapshot original; snapshot gravado antes desta resolução, cuja requisição trazia customer_id, responde 500 KYT_SNAPSHOT_INVALID e não reexecuta a análise. Dado não informado nunca vira “não”. customer_ref não muda: continua sendo a referência opaca do seu lado.

Com customer_ref informado, quando a leitura da identidade (chave de pseudonimização da referência) está indisponível, a resposta é 503 KYT_IDENTITY_UNAVAILABLE, com data.recommendation HOLD e data.fail_closed true: nenhuma análise é criada, nenhuma regra é avaliada e nada é cobrado. A decisão continua pertencendo ao cliente.

A sanção é medida na data da operação. Operação posterior ou igual à publicação vigente da lista é decidida pela versão publicada, informada em sanctions.coverage. Operação anterior à publicação depende do histórico oficial de designações e, sem ele, retorna HOLD com fail_closed verdadeiro. Fonte obrigatória vencida, não publicada ou não atestada também retorna HOLD, nunca ALLOW.

Nesta versão, exposição on-chain (exposures, graph e typologies) e blocklist de rede sem base de golpes carregada não são analisadas. A base atual cobre ETH e as redes EVM que a compartilham (BASE, ARB, BSC, MATIC, AVAX, OP e FTM). Essas dimensões saem em not_covered, no topo da resposta, nunca dentro de coverage. ALLOW com entradas em not_covered significa que elas não foram analisadas. Triagens gravadas antes desta versão não trazem o campo.

Item	Valor
Método	POST
Caminho	/vasp/screenings
URL	https://crypto-api.sentinexrisk.com/api/v1/vasp/screenings
Grupo	VASP - Screening
operationId	screenTransaction
Versão do contrato	8.5.1

Autenticação

Chave de API do tenant no header X-API-Key (esquema ApiKeyAuth). A chave identifica o tenant e carrega os escopos; não existe header de tenant. Detalhes em Autenticação.

Parâmetros

Nome	Em	Tipo	Obrigatório	Descrição
Idempotency-Key	header	string	não	Mesma chave + corpo igual = replay; corpo diferente = 409. Opcional: quando ausente e client_transaction_id presente, o servidor DERIVA a chave de (rota, corpo, janela), e a repetição idêntica vira replay em vez de segundo screening cobrado. O alcance da derivação é de no mínimo 10 e no máximo 20 minutos, porque a consulta prova o bucket corrente e o anterior. Sem client_transaction_id não há deduplicação possível e duas chamadas iguais continuam sendo duas operações. O prefixo snx-derived: é RESERVADO ao servidor em TODAS as rotas desta API: uma Idempotency-Key que comece com ele é recusada com 400. Até 255 caracteres.

Corpo da requisição

Corpo obrigatório.

Tipo de mídia application/json.

Tipo objeto.

Campo	Tipo	Obrigatório	Descrição
client_transaction_id	string	não
customer_ref	string	não	Referência opaca do cliente. Ocorrência inequívoca de CPF, CNPJ, e-mail ou telefone é substituída por hash determinístico antes de persistir, alertar ou notificar. Até 512 caracteres.
customer_id	string (uuid)	não	Opcional. UUID não nulo do titular matriculado: o id devolvido por POST /vasp/customers, com a mesma semântica do customer_id de POST /vasp/wallets. Omitir quando não houver titular. Valor vazio, null, UUID zero, fora do formato canônico de 36 caracteres ou de outro tipo responde 422 KYT_CUSTOMER_ID_INVALID. UUID bem formado que não identifica titular desta empresa não muda a decisão: a resposta traz holder_resolution NOT_FOUND. customer_ref continua como está. Exemplo: 00000000-0000-4000-8000-000000000001.
direction	string	não	Valores: DEPOSIT, WITHDRAWAL, INTERNAL.
asset	string	sim	Exemplo: USDT.
chain	string	não	Rede on-chain. OPCIONAL nesta rota, e continua opcional: o screening não grava a transação em histórico consultado por rede, então a ausência da chain não torna nada ilegível depois. Ela é, porém, necessária para triar a contraparte: sem chain, nem sanções nem blocklist consultam counterparty_address, e a decisão cai no fail-closed desta rota, voltando como HOLD com fail_closed: true e a razão declarada em reasons. Para consultar a contraparte nos dois caminhos, envie chain sempre que enviar counterparty_address. A rota irmã POST /transactions/analyze, que GRAVA a transação, é mais estrita: lá blockchain é obrigatória junto de qualquer endereço on-chain e a ausência devolve 400. Exemplo: tron.
counterparty_address	string	não
tx_hash	string	não	vazio = intenção pré-broadcast
operation_at	string (date-time)	não	Opcional. Data e hora da operação, em RFC 3339. É o instante em que a sanção da contraparte é medida contra o intervalo de designação da lista. A ausência NUNCA responde 400, nem com tx_hash preenchido: sem este campo o servidor usa a data do bloco da transação, quando já a mediu, e senão o instante em que recebeu a requisição. A origem da data usada volta em operation_time_source. Valor que não é data RFC 3339 responde 400 KYT_REQUEST_INVALID. Esta data não atesta obrigação legal e não altera a decisão final, que permanece do cliente.
amount	number (double) ou null	não	Quantidade do ativo indicado em asset, na unidade decimal nativa desse ativo. A omissão (ou null) impede a valoração no servidor e resulta em HOLD temporário. Para asset BRL o valor em reais é o próprio amount, inclusive zero informado. Valor negativo responde 400 KYT_AMOUNT_INVALID. Mínimo: 0. Exemplo: 1500.25.
fiat_value_brl	number (double) ou null	não	Valor em reais declarado pelo integrador, não em centavos. É apenas preservado e devolvido em declared_fiat_value_brl: não substitui a cotação do servidor e não tem efeito decisório. Valor não finito responde 400 KYT_FIAT_VALUE_INVALID. Exemplo: 7500.5.
counterparty_vasp	string	não
travel_rule	um de: string, boolean ou null	não	Estado informado de Travel Rule. Os booleanos true e false correspondem a REQUIRED e NOT_REQUIRED. Omissão ou null corresponde a UNKNOWN, sem HOLD por essa ausência. Outro valor responde 400 KYT_REQUEST_INVALID.

Alternativa de travel_rule: alternativa sem nome

Alternativa de travel_rule: alternativa sem nome

Exemplo de chamada

curl -X POST "https://crypto-api.sentinexrisk.com/api/v1/vasp/screenings" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d @corpo.json

O arquivo corpo.json segue o schema do corpo acima.

Respostas de sucesso

Status	Descrição
200	Recomendação de screening e estado da decisão do cliente

200

Recomendação de screening e estado da decisão do cliente

Tipo de mídia application/json.

Tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	não
idempotent_replay	boolean	não
data	objeto (VASPScreeningDecision)	não
data.screening_id	string (uuid)	sim
data.operation_at	string (date-time)	não	Data efetivamente usada na consulta de sanção por intervalo de designação, em UTC. Análise gravada antes desta data existir não traz o campo.
data.operation_time_source	string	não	Origem de operation_at, em ordem de precedência: OPERATION_AT (enviada pelo cliente), BLOCK_TIME (data do bloco da transação, quando o servidor já a mediu) e RECEIVED_AT (instante em que a requisição foi recebida). Valores: OPERATION_AT, BLOCK_TIME, RECEIVED_AT.
data.client_transaction_id	string	não
data.customer_id	string (uuid)	não	UUID informado na análise original. Presente junto de holder_resolution, e ausente quando a requisição não trouxe customer_id.
data.screen_status	string	sim	Valores: completed.
data.recommendation	string	sim	Recomendação auxiliar da Sentinex. Não é decisão operacional do cliente. DENY somente com base em sanção ou por regra de bloqueio configurada pela própria empresa; os demais riscos saem REVIEW. Valores: ALLOW, REVIEW, HOLD, DENY. Exemplo: REVIEW.
data.client_decision	objeto (KYTClientDecision)	sim	Decisão e desfecho atribuídos exclusivamente ao cliente.
data.client_decision.status	string	sim	Valores: PENDING_CLIENT_DECISION, RECORDED.
data.client_decision.authority	string	não	Valores: CLIENT_EXCHANGE.
data.client_decision.operational_action	string	não	Valores: ALLOW, HOLD, DENY.
data.client_decision.suspicion_outcome	string	não	Valores: SUSPICIOUS, NOT_SUSPICIOUS.
data.client_decision.rationale	string	não
data.client_decision.recorded_at	string (date-time)	não	Data e hora em RFC 3339, UTC.
data.risk_score	integer	sim	Score final limitado a 0 a 100 e arredondado uma única vez, com meio para cima. É o mesmo valor de score_ledger.final e do registro escalar da análise. A repetição idempotente e a consulta devolvem o snapshot gravado na análise original. Mínimo: 0. Máximo: 100. Exemplo: 70.
data.risk_level	string	sim	Faixa de risco em caixa alta. Exemplo: HIGH.
data.sanctions	objeto	sim	Resultado da triagem de sanções da contraparte. hit e state distinguem ausência de medição de resultado negativo: hit só sai booleano quando state é MEASURED, e sai nulo quando a sanção não foi medida. Categorias adversas não provam sanção.
data.sanctions.hit	boolean ou null	sim	Nulo quando state é NOT_MEASURED. Falso com state MEASURED é consulta negativa medida; nulo nunca vale como limpo.
data.sanctions.state	string (KYTMeasurementState)	não	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.sanctions.categories	lista de string	não	Ausente quando vazio, nunca nulo.
data.sanctions.provider	string	não
data.sanctions.provider_status	string	não
data.sanctions.evidence	lista de objeto (KYTSanctionEvidence) ou null	não	Fatos de sanção verificados para a contraparte. Nulo ou vazio quando não há fato verificado.
data.sanctions.evidence[].subject	string	sim	Valores: counterparty.
data.sanctions.evidence[].address	string	sim	Endereço consultado ao qual o fato se vincula.
data.sanctions.evidence[].list	string	sim	Lista de origem do fato. Nos fixtures do sandbox vale SANDBOX_FIXTURE. Exemplo: OPENSANCTIONS.
data.sanctions.evidence[].list_version	string	sim	Versão da lista fornecida pela fonte. Nos fixtures do sandbox é o identificador do catálogo sandbox-fixtures-v1.
data.sanctions.evidence[].list_date	string (date-time)	sim	Data fornecida pela lista, e não o horário da consulta.
data.sanctions.evidence[].match_type	string	sim	Valores: EXACT_ADDRESS.
data.sanctions.evidence[].source	string	sim	Origem do fato. Em produção vale SENTINEX_SANCTIONS_DATABASE; nos fixtures do sandbox vale SENTINEX_SANDBOX.
data.sanctions.evidence[].observed_at	string (date-time)	sim	Instante da consulta que observou o fato.
data.sanctions.evidence[].program	string	não	Programa da designação na fonte oficial. Omitido quando não medido.
data.sanctions.evidence[].designation_start	string (date-time)	não	Início inclusivo da designação, em UTC. Omitido enquanto a fonte não fornecer o intervalo; os produtores atuais ainda não o preenchem.
data.sanctions.evidence[].designation_end	string (date-time)	não	Fim exclusivo da designação, quando informado pela fonte. Omitido enquanto a fonte não fornecer o intervalo.
data.sanctions.coverage	lista de objeto (SanctionsSourceCoverage) ou null	não	Estado de cada fonte de sanções configurada nesta consulta.
data.sanctions.coverage[].source	string	sim	Exemplo: OPENSANCTIONS.
data.sanctions.coverage[].state	string (KYTMeasurementState)	sim	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.sanctions.coverage[].dataset	string	não
data.sanctions.coverage[].dataset_version	string	não
data.sanctions.coverage[].published_at	string (date-time)	não	Data de publicação informada pela fonte.
data.sanctions.coverage[].loaded_at	string (date-time)	não	Última leitura completa da fonte.
data.sanctions.coverage[].count	integer (int64)	não	Quantidade de endereços da versão. Omitido quando não medido. Mínimo: 1.
data.sanctions.coverage[].reason	string	não	Motivo de indisponibilidade, como stale ou snapshot_unavailable.
data.capabilities	objeto (KYTMeasuredCapabilities)	não	Capacidade de medição de cada dimensão da triagem, independente do status do provedor. MEASURED atesta apenas a capacidade nomeada, inclusive quando o resultado foi negativo. Os cinco campos saem sempre, com NOT_MEASURED quando a dimensão não foi medida. labels vale MEASURED também quando há etiqueta de bloqueio de emissor para o endereço (ver label_evidence). Ausência de evento não torna a dimensão MEASURED.
data.capabilities.sanctions	string (KYTMeasurementState)	sim	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.capabilities.labels	string (KYTMeasurementState)	sim	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.capabilities.exposures	string (KYTMeasurementState)	sim	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.capabilities.graph	string (KYTMeasurementState)	sim	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.capabilities.typologies	string (KYTMeasurementState)	sim	Estado de medição de uma dimensão. NOT_MEASURED significa que a dimensão não foi medida nesta consulta, e nunca vale como resultado negativo, zero ou lista vazia conclusiva. Valores: MEASURED, NOT_MEASURED.
data.label_evidence	lista de objeto (KYTIssuerBlockLabel)	não	Etiquetas de bloqueio de emissor de stablecoin (USDT e USDC) lidas de eventos públicos do contrato. Omitido quando nenhum evento foi coletado para o endereço: ausência de evento não prova que o endereço esteja livre. Efeito sempre LABEL_ONLY, nunca sanção, nunca score.
data.label_evidence[].source	string	sim	Valores: ISSUER_BLOCK_EVENT.
data.label_evidence[].issuer	string	sim	Valores: USDT, USDC.
data.label_evidence[].event	string	sim	Assinatura do evento do ABI público do contrato. Exemplo: Blacklisted(address).
data.label_evidence[].state	string	sim	Estado pelo evento mais recente, por (bloco, índice do log). Valores: BLOCKED, UNBLOCKED.
data.label_evidence[].contract	string	sim	Contrato do emissor que gravou o evento. Formato (expressão regular): ^0x[0-9a-f]{40}$.
data.label_evidence[].block_number	integer (int64)	sim	Mínimo: 0.
data.label_evidence[].block_time	string (date-time)	sim	Data do bloco que contém o evento, em UTC.
data.label_evidence[].tx_hash	string	sim	Formato (expressão regular): ^0x[0-9a-f]{64}$.
data.label_evidence[].effect	string	sim	Valores: LABEL_ONLY.
data.label_evidence[].recommendation	string	não	Recomendação da política da empresa quando state é BLOCKED. Nunca DENY e nunca ALLOW. Omitido quando state é UNBLOCKED. Valores: REVIEW, HOLD.
data.direct_exposure	objeto ou null	não	Exposição direta por categoria. Nulo quando capabilities.exposures é NOT_MEASURED, sem percentual fabricado a partir de rótulo.
data.indirect_exposure	objeto ou null	não	Exposição indireta por categoria. Nulo quando capabilities.exposures é NOT_MEASURED.
data.rule_hits	lista de objeto	sim
data.rule_hits[].rule_id	string	sim
data.rule_hits[].name	string	sim
data.rule_hits[].severity	string	sim
data.rule_hits[].weight	number (double)	sim
data.coverage	objeto (RuleCoverageSnapshot)	sim	Não aceita propriedades além das listadas.
data.coverage.manifest_version	string	sim	Valores: snx-rule-capabilities/2026-07-29.v1.
data.coverage.state	string	sim	Valores: ACTIVE_READY, ACTIVE_DEGRADED, DISABLED.
data.coverage.input_assessments	objeto	não	Estado das entradas amount_brl, aggregate_7d e travel_rule da triagem em tempo real, presente só na resposta de POST /vasp/screenings. Sem identificação do titular (customer_ref vazio), o agregado de 7 dias sai NOT_EVALUATED e não impõe retenção. Omitido em análises anteriores a esta medição.
data.coverage.evaluable_rules	lista de string	sim	Até 512 itens. Itens sem repetição.
data.coverage.degraded_rules	lista de objeto (RuleCoverageDegradedCapability)	sim	Até 512 itens.
data.coverage.degraded_rules[].rule_id	string	sim	Até 80 caracteres.
data.coverage.degraded_rules[].source	string	sim	Até 80 caracteres.
data.coverage.degraded_rules[].cause	string	sim	Valores: REQUIRED_INPUT_MISSING, SOURCE_UNAVAILABLE, SOURCE_STALE, MANIFEST_MISSING, ENGINE_UNAVAILABLE.
data.coverage.disabled_rules	lista de string	sim	Até 512 itens. Itens sem repetição.
data.coverage.causes	lista de string	sim	Até 16 itens. Itens sem repetição.
data.not_covered	lista de objeto	não	Dimensões que esta versão não analisa por desenho. Cada item traz rule_id, source e cause. Triagens gravadas antes desta versão não trazem o campo. ALLOW com entradas aqui significa que aquelas dimensões não foram analisadas, e não que o resultado delas foi negativo. Falha real do provedor, timeout ou erro de consulta continua em coverage.degraded_rules e retém a triagem; não entra neste campo.
data.not_covered[].rule_id	string	sim	Até 80 caracteres.
data.not_covered[].source	string	sim	Até 80 caracteres.
data.not_covered[].cause	string	sim	Valores: CAPABILITY_NOT_OFFERED, NETWORK_NOT_COVERED.
data.obligations	objeto	sim
data.obligations.travel_rule	string	sim	Valores: UNKNOWN, REQUIRED, NOT_REQUIRED.
data.obligations.coaf_sar	string	sim	Campo legado. O motor devolve MONITOR e não produz REPORTABLE por limiar monetário, portanto o valor não comprova obrigação objetiva de comunicação nem decisão de comunicar suspeição. Use coaf_objective para o estado objetivo (prévia).
data.obligations.decripto	string	sim
data.obligations.coaf_objective	objeto (CoafObjectivePreview)	não	Prévia objetiva do screening. Sem evento confirmado, o screening apenas devolve esta prévia, que nunca é comunicação definitiva.
data.obligations.coaf_objective.state	string	sim	Valores: INDETERMINADA.
data.obligations.coaf_objective.final	boolean	sim	Valores: false.
data.obligations.coaf_objective.gaps	lista de string	sim
data.amount_brl	number (double) ou null	sim	Valor em reais, não em centavos, calculado pelo servidor. Nulo quando a quantidade ou a cotação não estão disponíveis ou a cotação está vencida, o que retém a análise em HOLD temporário. Exemplo: 7500.5.
data.declared_fiat_value_brl	number (double) ou null	não	Valor declarado pelo integrador em fiat_value_brl, preservado para conferência. Não decide regras nem recomendação.
data.score_ledger	objeto (KYTScoreLedger)	não	Reconstrução do score. Comece por base, aplique cada item sobre o valor before para obter after (effective é after menos before), limite o resultado ao intervalo minimum a maximum e quantize uma única vez. O resultado é final, igual ao risk_score da resposta. O item de origem deep_lane_adjustment, quando presente, explicita a diferença entre o impacto total devolvido pelo avaliador de regras e as contribuições individuais disponíveis.
data.score_ledger.base	number	sim
data.score_ledger.minimum	number	sim	Valores: 0.
data.score_ledger.maximum	number	sim	Valores: 100.
data.score_ledger.quantization	string	sim	Valores: HALF_UP.
data.score_ledger.final	integer	sim	Mínimo: 0. Máximo: 100.
data.score_ledger.items	lista de objeto	sim
data.score_ledger.items[].source	string	sim
data.score_ledger.items[].operation	string	sim	Valores: MAX, ADD, FLOOR.
data.score_ledger.items[].before	number	sim
data.score_ledger.items[].operand	number	sim
data.score_ledger.items[].effective	number	sim
data.score_ledger.items[].after	number	sim
data.shadow_observations	lista de objeto (KYTShadowObservation)	não
data.shadow_observations[].screening_id	string (uuid)	sim
data.shadow_observations[].rule_id	string	sim
data.shadow_observations[].rule_name	string	sim
data.shadow_observations[].triggered	boolean	sim
data.shadow_observations[].score_impact	number	sim
data.fail_closed	boolean	sim
data.reasons	lista de string	não
data.latency_ms	integer (int64)	sim	Latência total em milissegundos. Mínimo: 0.
data.evaluated_at	string (date-time)	sim	Data e hora em RFC 3339, UTC. Exemplo: 2026-09-21T13:40:45Z.
data.api_version	string	sim	Valores: v1.
data.holder_resolution	string	não	Obrigatório na resposta de sucesso quando a requisição contém customer_id, independentemente do adicional. RESOLVED significa que o titular pertence à empresa autenticada; não atesta enriquecimento. NOT_FOUND inclui UUID desconhecido e UUID de outra empresa, sem alterar recomendação, score, motivos ou cobrança. Com cruzamento desligado, nenhuma fonte de KYC é lida. Sem customer_id, o campo não vem. Valores: RESOLVED, NOT_FOUND.
data.transaction	objeto	não	Presente somente depois de PATCH /vasp/screenings/{id}/tx-hash. O hash vindo no POST original não gera este objeto.
data.transaction.tx_hash	string	não
data.transaction.attached_at	string (date-time)	não
data.transaction.origin	string	não	Valores: TX_HASH_PATCH.

Códigos de erro declarados

Estes são os códigos que o contrato declara para esta operação. Os limites que valem para toda a API, antes da autenticação, estão em Limites de requisição.

Status	Descrição
400	Corpo, campo ou Idempotency-Key inválida (KYT_REQUEST_INVALID, KYT_ASSET_REQUIRED, KYT_AMOUNT_INVALID, KYT_IDEMPOTENCY_INVALID e os demais KYT_*_INVALID), ou operation_at mais de 5 minutos adiante do relógio do servidor (KYT_OPERATION_AT_IN_FUTURE), recusado antes de qualquer análise, persistência ou cobrança. Até 5 minutos é aceito como folga de relógio; a tolerância é parâmetro operacional, não prazo de norma.
401	A chave de API não autenticou a requisição, e nenhuma camada adiante rodou. error.code é missing_api_key (nenhuma chave em X-API-Key nem em Authorization: Bearer snxc_...) ou invalid_api_key (chave desconhecida, revogada ou expirada). Quando a plataforma não consegue verificar a chave, a resposta é 503 com api_key_verification_unavailable, e não 401: repita com backoff.
402	Conta sem direito comercial (TRIAL_EXPIRED): trial vencido, trial sem data ou empresa sem contrato. A requisição NÃO foi processada; uma triagem recusada assim é transação não triada, nunca aprovada.
403	Acesso recusado antes da operação. Além das recusas de ErroAcessoNegado (escudo de borda, IP da chave, ambiente, conta e escopo), a empresa pode não ter o módulo de KYT contratado (ModuleNotEnabledResponse, MODULE_NOT_ENABLED, com details.module). Não repita sem corrigir a causa.
404	Com chave válida, o caminho ou o método não corresponde a operação servida por esta implantação (error.code route_not_found). Confira método, caminho e o prefixo /api/v1.
409	Idempotency-Key reusada com corpo diferente (KYT_IDEMPOTENCY_CONFLICT) ou análise idêntica em processamento (KYT_IDEMPOTENCY_IN_PROGRESS).
413	Corpo acima de 1 MiB, recusado pelo escudo de borda antes da autenticação (code BODY_TOO_LARGE). Nada foi processado.
422	Transação que o motor não consegue analisar com os dados enviados (KYT_INPUT_UNSCREENABLE), ou customer_id inválido (KYT_CUSTOMER_ID_INVALID: vazio, nulo, UUID zero, fora do formato canônico ou de outro tipo); nos dois casos a análise não roda. No sandbox do desenvolvedor (sandbox.api.crypto.sentinexrisk.com), também endereço de contraparte que não é uma das fixtures do catálogo sandbox-fixtures-v1 (SANDBOX_FIXTURE_NOT_SUPPORTED, no mesmo envelope KYTPublicErrorResponse, com action apontando para /api/v1/sandbox/fixtures): nenhuma consulta de DNS ou de provider é feita nem cobrança. A produção nunca emite este código.
429	Limite de requisições atingido; nada foi processado. Formas, pela camada que recusou: limite da chave (ErrorResponseCoded, api_key_rate_limit_exceeded, 60 por minuto quando a chave não define outro valor, Retry-After: 60); limite global por hora (ErroLimite, retry_after 3600 e Retry-After: 3600); escudo de borda por IP (ErroLimite: RATE_LIMIT_HARD acima de 1.000 por minuto, com 300 segundos; IP_BANNED no bloqueio temporário; e a rajada com intervalo menor que 50 ms, que vem sem Retry-After e sem retry_after). A busca de clientes tem limite próprio (error rate_limited, com retry_after e detail) e o laudo também (error RATE_LIMIT_EXCEEDED, 120 por hora por IP, Retry-After: 3600). No sandbox, chamadas VASP autenticadas também usam sandbox_simulator_rate_limit_exceeded: 60 por minuto por key, 300 por minuto por empresa e 10.000 por dia UTC por empresa. Essa recusa inclui Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining: 0. Espere o Retry-After quando ele vier.
500	Falha inesperada (ErroTexto) ou análise gravada que não pôde ser lida na repetição (KYT_SNAPSHOT_INVALID).
503	Evidência essencial, persistência, auditoria, medição ou motor indisponível (KYT_*_UNAVAILABLE, incluindo KYT_HOLDER_UNAVAILABLE quando a resolução ou a evidência do titular falha), ou leitura do módulo contratado indisponível (MODULE_STORE_UNAVAILABLE). A identidade indisponível (KYT_IDENTITY_UNAVAILABLE) usa o envelope público de erro acrescido de data.recommendation HOLD e data.fail_closed true, sem criar análise, avaliar regras ou registrar consumo. As camadas anteriores à operação também respondem 503, nada processado: limitador por IP ou da empresa sem contagem (ErroTexto), estado da conta (empresa_ACCESS_STATE_UNAVAILABLE) e limitador da chave (rate_limit_unavailable) e verificação da chave (api_key_verification_unavailable).

400

Corpo, campo ou Idempotency-Key inválida (KYT_REQUEST_INVALID, KYT_ASSET_REQUIRED, KYT_AMOUNT_INVALID, KYT_IDEMPOTENCY_INVALID e os demais KYT_*_INVALID), ou operation_at mais de 5 minutos adiante do relógio do servidor (KYT_OPERATION_AT_IN_FUTURE), recusado antes de qualquer análise, persistência ou cobrança. Até 5 minutos é aceito como folga de relógio; a tolerância é parâmetro operacional, não prazo de norma.

Tipo de mídia application/json.

Schema KYTPublicErrorResponse, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	objeto	sim
error.code	string	sim	Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status	integer	sim	Exemplo: 503.
error.message	string	sim
error.action	string	sim
error.retriable	boolean	sim
error.retry_after_seconds	integer	não	Mínimo: 1.
error.request_id	string	não
error.reason	string	não	Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

401

A chave de API não autenticou a requisição, e nenhuma camada adiante rodou. error.code é missing_api_key (nenhuma chave em X-API-Key nem em Authorization: Bearer snxc_...) ou invalid_api_key (chave desconhecida, revogada ou expirada). Quando a plataforma não consegue verificar a chave, a resposta é 503 com api_key_verification_unavailable, e não 401: repita com backoff.

Resposta compartilhada ErroChaveNaoAutenticada do contrato.

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

402

Conta sem direito comercial (TRIAL_EXPIRED): trial vencido, trial sem data ou empresa sem contrato. A requisição NÃO foi processada; uma triagem recusada assim é transação não triada, nunca aprovada.

Resposta compartilhada TenantAccessPaymentRequired do contrato.

Tipo de mídia application/json.

Schema TenantAccessRefusalResponse, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code	string	sim	Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details	objeto	não
details.reason	string	não	Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at	string (date-time)	não	Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state	string	não	Presente em empresa_NOT_OPERATIONAL.

403

Acesso recusado antes da operação. Além das recusas de ErroAcessoNegado (escudo de borda, IP da chave, ambiente, conta e escopo), a empresa pode não ter o módulo de KYT contratado (ModuleNotEnabledResponse, MODULE_NOT_ENABLED, com details.module). Não repita sem corrigir a causa.

Resposta compartilhada ErroAcessoNegadoModuloKYT do contrato.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, TenantAccessRefusalResponse, ErroTexto, ModuleNotEnabledResponse.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

Alternativa do corpo: TenantAccessRefusalResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code	string	sim	Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details	objeto	não
details.reason	string	não	Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at	string (date-time)	não	Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state	string	não	Presente em empresa_NOT_OPERATIONAL.

Alternativa do corpo: ErroTexto

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Carteira não encontrada..

Alternativa do corpo: ModuleNotEnabledResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Este recurso não está habilitado no contrato atual..
code	string	sim	Valores: MODULE_NOT_ENABLED.
details	objeto	não
details.module	string	não	Código do módulo no catálogo. Exemplo: mod_crypto_sanctions.

404

Com chave válida, o caminho ou o método não corresponde a operação servida por esta implantação (error.code route_not_found). Confira método, caminho e o prefixo /api/v1.

Resposta compartilhada ErroRotaNaoEncontrada do contrato.

Tipo de mídia application/json.

Schema ErrorResponseCoded, do tipo objeto.

Envelope de erro codificado (middlewares de API key e erros de negócio da superfície VASP). Trate error.code como contrato estável; error.message é texto livre.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

409

Idempotency-Key reusada com corpo diferente (KYT_IDEMPOTENCY_CONFLICT) ou análise idêntica em processamento (KYT_IDEMPOTENCY_IN_PROGRESS).

Tipo de mídia application/json.

Schema KYTPublicErrorResponse, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	objeto	sim
error.code	string	sim	Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status	integer	sim	Exemplo: 503.
error.message	string	sim
error.action	string	sim
error.retriable	boolean	sim
error.retry_after_seconds	integer	não	Mínimo: 1.
error.request_id	string	não
error.reason	string	não	Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

413

Corpo acima de 1 MiB, recusado pelo escudo de borda antes da autenticação (code BODY_TOO_LARGE). Nada foi processado.

Resposta compartilhada ErroCorpoAcimaDoLimite do contrato.

Tipo de mídia application/json.

Schema ErroTextoComCodigo, do tipo objeto.

Envelope de erro com a mensagem em texto em error e o código estável em code, na raiz do corpo. Na API de KYT aparece no corpo acima de 1 MiB (BODY_TOO_LARGE, 413) e na leitura do módulo contratado que não pôde ser feita (MODULE_STORE_UNAVAILABLE, 503).

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim
code	string	sim	Exemplo: BODY_TOO_LARGE.

422

Transação que o motor não consegue analisar com os dados enviados (KYT_INPUT_UNSCREENABLE), ou customer_id inválido (KYT_CUSTOMER_ID_INVALID: vazio, nulo, UUID zero, fora do formato canônico ou de outro tipo); nos dois casos a análise não roda. No sandbox do desenvolvedor (sandbox.api.crypto.sentinexrisk.com), também endereço de contraparte que não é uma das fixtures do catálogo sandbox-fixtures-v1 (SANDBOX_FIXTURE_NOT_SUPPORTED, no mesmo envelope KYTPublicErrorResponse, com action apontando para /api/v1/sandbox/fixtures): nenhuma consulta de DNS ou de provider é feita nem cobrança. A produção nunca emite este código.

Tipo de mídia application/json.

Schema KYTPublicErrorResponse, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	objeto	sim
error.code	string	sim	Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status	integer	sim	Exemplo: 503.
error.message	string	sim
error.action	string	sim
error.retriable	boolean	sim
error.retry_after_seconds	integer	não	Mínimo: 1.
error.request_id	string	não
error.reason	string	não	Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

429

Limite de requisições atingido; nada foi processado. Formas, pela camada que recusou: limite da chave (ErrorResponseCoded, api_key_rate_limit_exceeded, 60 por minuto quando a chave não define outro valor, Retry-After: 60); limite global por hora (ErroLimite, retry_after 3600 e Retry-After: 3600); escudo de borda por IP (ErroLimite: RATE_LIMIT_HARD acima de 1.000 por minuto, com 300 segundos; IP_BANNED no bloqueio temporário; e a rajada com intervalo menor que 50 ms, que vem sem Retry-After e sem retry_after). A busca de clientes tem limite próprio (error rate_limited, com retry_after e detail) e o laudo também (error RATE_LIMIT_EXCEEDED, 120 por hora por IP, Retry-After: 3600). No sandbox, chamadas VASP autenticadas também usam sandbox_simulator_rate_limit_exceeded: 60 por minuto por key, 300 por minuto por empresa e 10.000 por dia UTC por empresa. Essa recusa inclui Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining: 0. Espere o Retry-After quando ele vier.

Resposta compartilhada ErroLimiteDeRequisicoes do contrato.

Header	Tipo	Descrição
Retry-After	integer	Segundos a esperar antes de repetir. Vem nos 429 dos limitadores (salvo a rajada do escudo) e no 503 de transação que conflitou (1 segundo).
X-RateLimit-Limit	integer	Teto da janela do limitador que respondeu, quando ele informa.
X-RateLimit-Remaining	integer	Requisições restantes na janela, quando o limitador informa.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, ErroLimite.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

Alternativa do corpo: ErroLimite

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Too many requests. Please try again later..
retry_after	integer	não	Mínimo: 1. Exemplo: 3600.
code	string	não	Exemplo: RATE_LIMIT_HARD.
reference	string	não	Identificador curto do bloqueio, para citar ao suporte.
detail	string	não

500

Falha inesperada (ErroTexto) ou análise gravada que não pôde ser lida na repetição (KYT_SNAPSHOT_INVALID).

Tipo de mídia application/json.

Tipo um de: ErroTexto, KYTPublicErrorResponse.

Alternativa do corpo: ErroTexto

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Carteira não encontrada..

Alternativa do corpo: KYTPublicErrorResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	objeto	sim
error.code	string	sim	Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status	integer	sim	Exemplo: 503.
error.message	string	sim
error.action	string	sim
error.retriable	boolean	sim
error.retry_after_seconds	integer	não	Mínimo: 1.
error.request_id	string	não
error.reason	string	não	Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

503

Evidência essencial, persistência, auditoria, medição ou motor indisponível (KYT_*_UNAVAILABLE, incluindo KYT_HOLDER_UNAVAILABLE quando a resolução ou a evidência do titular falha), ou leitura do módulo contratado indisponível (MODULE_STORE_UNAVAILABLE). A identidade indisponível (KYT_IDENTITY_UNAVAILABLE) usa o envelope público de erro acrescido de data.recommendation HOLD e data.fail_closed true, sem criar análise, avaliar regras ou registrar consumo. As camadas anteriores à operação também respondem 503, nada processado: limitador por IP ou da empresa sem contagem (ErroTexto), estado da conta (empresa_ACCESS_STATE_UNAVAILABLE) e limitador da chave (rate_limit_unavailable) e verificação da chave (api_key_verification_unavailable).

Header	Tipo	Descrição
Retry-After	integer	Segundos a esperar antes de repetir. Vem nos 429 dos limitadores (salvo a rajada do escudo) e no 503 de transação que conflitou (1 segundo).

Tipo de mídia application/json.

Tipo um de: ErroTexto, TenantAccessRefusalResponse, ErrorResponseCoded, ErroTextoComCodigo, KYTPublicErrorResponse, KYTIdentityUnavailableResponse.

Alternativa do corpo: ErroTexto

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Carteira não encontrada..

Alternativa do corpo: TenantAccessRefusalResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim	Exemplo: Seu período de teste terminou. Fale com a Sentinex Risk para estender o teste ou contratar um plano..
code	string	sim	Valores: TRIAL_EXPIRED, TENANT_SUSPENDED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED, TENANT_ACCESS_DENIED, TENANT_ACCESS_STATE_UNAVAILABLE.
details	objeto	não
details.reason	string	não	Presente em TRIAL_EXPIRED. Valores: TRIAL_WITHOUT_END_DATE, TRIAL_ENDED, POC_TRIAL_RETIRED, DEMO_WITHOUT_COMMERCIAL_ACCESS, NO_COMMERCIAL_ACCESS.
details.trial_ends_at	string (date-time)	não	Presente em TRIAL_EXPIRED quando o trial tem data.
details.lifecycle_state	string	não	Presente em empresa_NOT_OPERATIONAL.

Alternativa do corpo: ErrorResponseCoded

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Exemplo: missing_api_key.
error.message	string	sim	Exemplo: X-API-Key header required.

Alternativa do corpo: ErroTextoComCodigo

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	string	sim
code	string	sim	Exemplo: BODY_TOO_LARGE.

Alternativa do corpo: KYTPublicErrorResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
error	objeto	sim
error.code	string	sim	Exemplo: KYT_DEPENDENCY_UNAVAILABLE.
error.http_status	integer	sim	Exemplo: 503.
error.message	string	sim
error.action	string	sim
error.retriable	boolean	sim
error.retry_after_seconds	integer	não	Mínimo: 1.
error.request_id	string	não
error.reason	string	não	Causa do 400 KYT_WALLET_INVALID no laudo: address_chain_mismatch diz que o endereço não é válido para a rede informada (rede desconhecida, checksum inválido ou forma de outra rede). O par é validado antes de qualquer consulta externa. Ausente nos demais erros. Valores: address_chain_mismatch.

Alternativa do corpo: KYTIdentityUnavailableResponse

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Valores: false.
data	objeto	sim
data.recommendation	string	sim	Valores: HOLD.
data.fail_closed	boolean	sim	Valores: true.
error	objeto	sim
error.code	string	sim	Valores: KYT_IDENTITY_UNAVAILABLE.
error.http_status	integer	sim	Valores: 503.
error.message	string	sim
error.action	string	sim
error.retriable	boolean	sim	Valores: true.
error.retry_after_seconds	integer	sim	Valores: 30.
error.request_id	string	não