POST /vasp/kyt-report

Gera laudo KYT por API key

Gera o laudo sobre uma carteira da própria empresa. Requer o escopo vasp:transactions:screen e o módulo KYT. format aceita pdf, html ou json. O JSON usa recommendation; a decisão operacional continua pendente até o cliente registrá-la.

O par endereço/rede é validado antes de qualquer consulta externa: par inválido responde 400 KYT_WALLET_INVALID com reason address_chain_mismatch e nenhuma chamada externa é feita. report.id é o identificador único da emissão e case.case_id o agrupador estável da carteira, na forma canônica (veja KYTReportJSON para a compatibilidade com laudos anteriores). Valor em reais sem cotação completa não sai no JSON (scope.brl_status nao_cotado), e o monitoramento só é afirmado quando uma fonte o comprova (monitoring).

Item	Valor
Método	`POST`
Caminho	`/vasp/kyt-report`
URL	`https://crypto-api.sentinexrisk.com/api/v1/vasp/kyt-report`
Grupo	VASP - Screening
operationId	`generateVASPKYTReport`
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
`format`	query	string	não	Valores: `pdf`, `html`, `json`. Padrão: `pdf`.
`profile`	query	string	não	Valores: `operational`, `complete`, `regulatory`. Padrão: `operational`.
`Accept`	header	string	não	application/vnd.sentinex.kyt.v2+json seleciona a projeção documental canônica; application/json preserva v1.

Corpo da requisição

Corpo obrigatório.

Tipo de mídia application/json.

Schema KYTReportRequest, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
`profile`	string	não	Valores: `operational`, `complete`, `regulatory`.
`wallet`	objeto	sim
`wallet.address`	string	sim	Ao menos 1 caractere(s).
`wallet.blockchain`	string	sim	Identificador da rede em minúsculas. Exemplo: `ethereum`.

Exemplo de corpo, publicado no contrato:

{
  "profile": "operational",
  "wallet": {
    "address": "0x1111111111111111111111111111111111111111",
    "blockchain": "ethereum"
  }
}

Exemplo de chamada

curl -X POST "https://crypto-api.sentinexrisk.com/api/v1/vasp/kyt-report" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Accept: <Accept>" \
  -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`	Laudo gerado e emissão registrada na auditoria

200

Laudo gerado e emissão registrada na auditoria

Header	Tipo	Descrição
`Content-Disposition`	string	PDF canônico, quando o snapshot está presente: `KYT-OPERACIONAL-<report-id>.pdf`, `KYT-COMPLETO-<report-id>.pdf` ou `KYT-REGULATORIO-<report-id>.pdf`. Sem snapshot canônico permanece o formato legado `kyt-{perfil}-{emitido-em-UTC}-{report-id}.{formato}` (por exemplo, `kyt-operational-20261002T120000Z-<report-id>.pdf`). `attachment` no PDF; `inline` no HTML e no JSON. Exposto ao navegador pelo CORS.
`X-Report-Format`	string	`html` ou `json` quando o artefato é HTML ou JSON; ausente no PDF. Exposto ao navegador pelo CORS.
`X-Report-Audit-Trail`	string	`recorded` quando a emissão foi gravada no histórico imutável da empresa, `not-recorded` quando não foi.

Tipo de mídia application/json.

Schema KYTReportJSON, do tipo objeto.

Laudo KYT estruturado. Campos monetários estão em unidades decimais e datas usam RFC 3339 UTC.

report.id é o identificador único da emissão (ULID, cujo instante é o da emissão) e é o mesmo do nome do arquivo e da auditoria. case.case_id é o agrupador estável da carteira e vem separado, na forma KYT-WALLET-<REDE>-<hash do endereço canônico>, com a rede em maiúsculas no nome canônico (ETHEREUM, não o apelido digitado) e o hash sobre o endereço na forma canônica: grafias do mesmo endereço (checksum ou minúsculo) e da mesma rede dão o mesmo case_id. Compatibilidade: laudos emitidos antes da 2.16.0 e lidos do histórico trazem o case_id na forma antiga, calculada sobre a rede e o endereço como digitados, e report.id igual ao case_id. A mesma carteira pode, por isso, aparecer em dois grupos (um antigo e um novo) até o histórico anterior expirar. Não una os dois pelo texto do case_id.

Valores em reais (*_brl) só existem com cotação completa. Sem ela, scope.brl_status é nao_cotado e nenhum campo em reais aparece no JSON: trate a ausência como “não cotado”, nunca como zero.

Aceita propriedades além das listadas.

Campo	Tipo	Obrigatório	Descrição
`api_version`	string	sim	Valores: `v1`.
`service_role`	string	sim	Valores: `AUXILIARY_ANALYSIS_SERVICE`.
`report`	objeto	sim	Aceita propriedades além das listadas.
`report.id`	string	não	Identificador único da emissão (ULID). Até a 2.15.x repetia o `case_id`. Formato (expressão regular): `^[0-9A-HJKMNP-TV-Z]{26}$`.
`report.case_id`	string	não	Mesmo valor de `case.case_id`.
`case`	objeto	sim	Aceita propriedades além das listadas.
`case.case_id`	string	não	Exemplo: `KYT-WALLET-ETHEREUM-0000000000000000`.
`scope`	objeto (`KYTReportScope`)	não	Escopo do laudo (carteiras, redes, janela e valores). Aceita propriedades além das listadas.
`scope.brl_status`	string	não	Estado de TODOS os valores em reais do laudo. `medido` exige cotação completa (`brl_quote`). Em `nao_cotado`, nenhum campo `*_brl` (`volume_brl`, `direct_brl`, `indirect_brl`, `total_brl`, `value_brl`) sai no JSON e o documento imprime `NÃO COTADO`, nunca `R$ 0,00`. Valores: `medido`, `nao_cotado`.
`scope.brl_quote`	objeto (`KYTReportBRLQuote`)	não	Cotação que sustenta os valores em reais. Presente somente com os quatro elementos; faltando qualquer um, `brl_status` é `nao_cotado`.
`scope.brl_quote.origin_currency`	string	sim
`scope.brl_quote.rate`	string	sim	Taxa em texto decimal, sem arredondamento.
`scope.brl_quote.source`	string	sim
`scope.brl_quote.quoted_at`	string (date-time)	sim
`scope.volume_brl`	number (double)	não	Ausente quando `brl_status` é `nao_cotado`.
`monitoring`	objeto (`KYTReportMonitoring`)	não	Estado de monitoramento da carteira comprovado por uma fonte nesta emissão. Ausente significa que nenhuma fonte o comprovou, e o documento imprime `NÃO COMPROVADO NESTA EMISSÃO` em vez de afirmar monitoramento contínuo.
`monitoring.status`	string	sim
`monitoring.source`	string	sim
`monitoring.observed_at`	string (date-time)	sim
`attribution`	lista de objeto	não
`attribution[].vasp`	boolean ou null	não	`true`, `false` ou `null` (não determinado). Contraparte observada on-chain sem atribuição de entidade traz `null`: nunca leia ausência de classificação como “não é VASP”.
`exposure_summary`	lista de objeto	não
`exposure_summary[].direct_brl`	number (double)	não
`exposure_summary[].indirect_brl`	number (double)	não
`exposure_summary[].total_brl`	number (double)	não
`hop_ladder`	lista de objeto	não
`hop_ladder[].volume_brl`	number (double)	não
`source_of_funds`	lista de objeto	não
`source_of_funds[].value_brl`	number (double)	não
`destination_of_funds`	lista de objeto	não
`destination_of_funds[].value_brl`	number (double)	não
`verdict`	objeto	sim	Aceita propriedades além das listadas.
`verdict.recommendation`	string	sim	Valores: `ALLOW`, `REVIEW`, `HOLD`, `DENY`.
`verdict.risk_tier`	string	sim
`verdict.score_total`	integer	sim	Mínimo: 0. Máximo: 100.
`conclusion`	objeto	sim	Aceita propriedades além das listadas.
`conclusion.recommendation`	string	sim	Valores: `ALLOW`, `REVIEW`, `HOLD`, `DENY`.
`client_decision`	objeto (`KYTClientDecision`)	sim	Decisão e desfecho atribuídos exclusivamente ao cliente.
`client_decision.status`	string	sim	Valores: `PENDING_CLIENT_DECISION`, `RECORDED`.
`client_decision.authority`	string	não	Valores: `CLIENT_EXCHANGE`.
`client_decision.operational_action`	string	não	Valores: `ALLOW`, `HOLD`, `DENY`.
`client_decision.suspicion_outcome`	string	não	Valores: `SUSPICIOUS`, `NOT_SUSPICIOUS`.
`client_decision.rationale`	string	não
`client_decision.recorded_at`	string (date-time)	não	Data e hora em RFC 3339, UTC.

Tipo de mídia application/vnd.sentinex.kyt.v2+json.

Schema KYTReportDocumentV2, do tipo objeto.

Projeção do perfil emitido, sem o snapshot factual privado. Não é compatível com KYTReportJSON v1.

Não aceita propriedades além das listadas.

Campo	Tipo	Obrigatório	Descrição
`report_id`	string	sim
`case_id`	string	sim
`profile`	string	sim	Valores: `operacional`, `completo`, `regulatorio`.
`metadata`	objeto	sim
`sections`	lista de objeto	sim
`sections[].narrative`	objeto	sim	Aceita propriedades além das listadas.
`sections[].tables`	lista de objeto ou null	sim
`sections[].tables[].headers`	lista de string	não
`sections[].tables[].rows`	lista de lista de string	não
`graph`	objeto	não	Grafo público, omitido no perfil operacional. Aceita propriedades além das listadas.

Tipo de mídia application/pdf.

Tipo string (binary).

Tipo de mídia text/html.

Tipo string.

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`	Carteira, rede, perfil ou formato inválido (`KYT_REQUEST_INVALID`, `KYT_WALLET_REQUIRED`, `KYT_WALLET_INVALID`, `KYT_REPORT_PROFILE_INVALID`, `KYT_REPORT_FORMAT_INVALID`).
`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`.
`413`	Corpo acima de 1 MiB, recusado pelo escudo de borda antes da autenticação (`code` `BODY_TOO_LARGE`). Nada foi processado.
`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. A mensagem é genérica de propósito; guarde o `X-Request-ID` da resposta para o suporte e repita com espera.
`502`	Evidência on-chain ou renderização do laudo falhou no provedor (`KYT_EVIDENCE_UNAVAILABLE`, `KYT_REPORT_RENDER_FAILED`, `KYT_REPORT_SERIALIZATION_FAILED`).
`503`	Dependência essencial, auditoria, renderização ou transação da requisição indisponível (`KYT_SERVICE_UNAVAILABLE`, `KYT_EVIDENCE_UNAVAILABLE`, `KYT_AUDIT_UNAVAILABLE`, `KYT_REPORT_RENDER_UNAVAILABLE`, ou texto em `error`), ou leitura do módulo contratado indisponível (`MODULE_STORE_UNAVAILABLE`). 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

Carteira, rede, perfil ou formato inválido (KYT_REQUEST_INVALID, KYT_WALLET_REQUIRED, KYT_WALLET_INVALID, KYT_REPORT_PROFILE_INVALID, KYT_REPORT_FORMAT_INVALID).

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`.

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`.

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. A mensagem é genérica de propósito; guarde o X-Request-ID da resposta para o suporte e repita com espera.

Resposta compartilhada ErroInterno do contrato.

Tipo de mídia application/json.

Schema ErroTexto, do tipo objeto.

Envelope de erro com a mensagem em texto no campo error, sem código. É o formato dos handlers de cadastro, carteira, webhooks, ledger e leituras regulatórias, da recuperação de falha inesperada (500), da indisponibilidade das camadas de borda (503) e da recusa do escudo de borda por padrão de ataque (403). Ramifique pelo status HTTP; a mensagem é texto livre e pode mudar.

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

502

Evidência on-chain ou renderização do laudo falhou no provedor (KYT_EVIDENCE_UNAVAILABLE, KYT_REPORT_RENDER_FAILED, KYT_REPORT_SERIALIZATION_FAILED).

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`.

503

Dependência essencial, auditoria, renderização ou transação da requisição indisponível (KYT_SERVICE_UNAVAILABLE, KYT_EVIDENCE_UNAVAILABLE, KYT_AUDIT_UNAVAILABLE, KYT_REPORT_RENDER_UNAVAILABLE, ou texto em error), ou leitura do módulo contratado indisponível (MODULE_STORE_UNAVAILABLE). 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.

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`.

POST /vasp/kyt-report

Autenticação

Parâmetros

Corpo da requisição

Exemplo de chamada

Respostas de sucesso

200

Códigos de erro declarados

400

401

402

403

Alternativa do corpo: ErrorResponseCoded

Alternativa do corpo: TenantAccessRefusalResponse

Alternativa do corpo: ErroTexto

Alternativa do corpo: ModuleNotEnabledResponse

404

413

429

Alternativa do corpo: ErrorResponseCoded

Alternativa do corpo: ErroLimite

500

502

503

Alternativa do corpo: ErroTexto

Alternativa do corpo: TenantAccessRefusalResponse

Alternativa do corpo: ErrorResponseCoded

Alternativa do corpo: ErroTextoComCodigo

Alternativa do corpo: KYTPublicErrorResponse

Alternativa do corpo: `ErrorResponseCoded`

Alternativa do corpo: `TenantAccessRefusalResponse`

Alternativa do corpo: `ErroTexto`

Alternativa do corpo: `ModuleNotEnabledResponse`

Alternativa do corpo: `ErrorResponseCoded`

Alternativa do corpo: `ErroLimite`

Alternativa do corpo: `ErroTexto`

Alternativa do corpo: `TenantAccessRefusalResponse`

Alternativa do corpo: `ErrorResponseCoded`

Alternativa do corpo: `ErroTextoComCodigo`

Alternativa do corpo: `KYTPublicErrorResponse`