Quickstart

A integração máquina a máquina usa o header X-API-Key na superfície /vasp. A chave identifica o tenant e carrega os escopos: nenhum header de tenant é necessário.

Existem dois ambientes, cada um com a sua base e o seu tipo de chave. Todos os caminhos do contrato são relativos à base, e o prefixo /v1 sozinho responde 404.

Ambiente	Base	Chave
Sandbox	`https://sandbox.api.crypto.sentinexrisk.com/api/v1`	`snxc_sand_...`
Produção	`https://crypto-api.sentinexrisk.com/api/v1`	`snxc_live_...`

Conta liberada para a API

A chave só é aceita quando a conta do tenant está em estado operacional e com o acesso por API liberado pela Sentinex Risk. Quando não está, qualquer chamada responde 402 ou 403 com o motivo no campo code (TRIAL_EXPIRED, TENANT_NOT_OPERATIONAL, API_ACCESS_DISABLED e outros), antes de chegar à operação.
Gerar a chave de sandbox
- No painel, entre com a conta de teste, abra Desenvolvedores > Chaves e uso da API e clique em Nova API key
- Escolha os escopos mínimos. Para os passos abaixo: vasp:read e vasp:transactions:screen
- A chave de sandbox é emitida na hora e vale até 30 dias
- Copie a chave na hora: o servidor guarda só o resumo dela e não a mostra de novo (formato snxc_sand_<identificador>_<segredo>)
O passo a passo com as telas está no Guia de chaves de API.
Primeira chamada autenticada

Esta leitura confere a chave, o ambiente e o acesso da conta sem gravar nada. Escopo: vasp:read.
Janela do terminal
```
export SENTINEX_API_KEY='snxc_sand_<sua_chave>'
export SENTINEX_BASE_URL='https://sandbox.api.crypto.sentinexrisk.com/api/v1'

curl "$SENTINEX_BASE_URL/vasp/alerts?limit=1" \
  -H "X-API-Key: $SENTINEX_API_KEY"
```
Resposta em um tenant sem alertas:
```
{
  "success": true,
  "data": [],
  "pagination": { "total": 0, "limit": 1, "offset": 0 }
}
```
Chave ausente ou inválida responde 401 com error.code igual a missing_api_key ou invalid_api_key. Uma chave de outro ambiente não autentica: a resposta é 401 com invalid_api_key, ou 403 com api_key_environment_not_allowed quando o prefixo já indica outro ambiente, antes da autenticação, ou o ambiente registrado é recusado. Confira se o prefixo da chave e a base são do mesmo ambiente.
Analisar uma transação

POST /vasp/screenings devolve, na mesma resposta, a recomendação da Sentinex Risk: ALLOW, REVIEW, HOLD ou DENY, com score, sanções e regras acionadas. A recomendação é análise auxiliar; a decisão operacional é sua. Escopo: vasp:transactions:screen.

No sandbox, a contraparte precisa ser uma das fixtures de Homologação e testes. O endereço abaixo é a fixture de baixo risco.
Janela do terminal
```
CHAVE="$(uuidgen)"   # uma por operação; numa repetição, reenvie a mesma

curl -X POST "$SENTINEX_BASE_URL/vasp/screenings" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CHAVE" \
  -d '{
    "client_transaction_id": "pedido-0001",
    "customer_ref": "cliente-42",
    "direction": "WITHDRAWAL",
    "asset": "ETH",
    "chain": "ethereum",
    "counterparty_address": "0x7eae68ba864d7e60463ca6842c53f1b20ecfb1a2",
    "amount": 1.5,
    "fiat_value_brl": 7500.5
  }'
```
Só asset é obrigatório. Envie chain sempre que enviar counterparty_address: sem a rede, a contraparte não é consultada e a análise volta como HOLD com fail_closed: true. No sandbox, um endereço que não seja fixture responde 422 com SANDBOX_FIXTURE_NOT_SUPPORTED.

Recorte dos campos principais da resposta (o schema completo está em POST /vasp/screenings). O endereço acima é a fixture fx-kyt-low-v1. A resposta atual também traz not_covered, capabilities, direct_exposure, indirect_exposure, score_ledger, shadow_observations, operation_at, operation_time_source e declared_fiat_value_brl (este último ecoa o fiat_value_brl enviado).
```
{
  "success": true,
  "data": {
    "screening_id": "0b8f3c2e-5a7d-4e61-9f2b-1c3d4e5f6a7b",
    "client_transaction_id": "pedido-0001",
    "screen_status": "completed",
    "recommendation": "ALLOW",
    "client_decision": { "status": "PENDING_CLIENT_DECISION" },
    "risk_score": 5,
    "risk_level": "LOW",
    "fail_closed": false,
    "api_version": "v1",
    "operation_at": "2026-10-01T12:00:00Z",
    "operation_time_source": "RECEIVED_AT",
    "declared_fiat_value_brl": 7500.5,
    "capabilities": {
      "sanctions": "MEASURED",
      "labels": "NOT_MEASURED",
      "exposures": "NOT_MEASURED",
      "graph": "NOT_MEASURED",
      "typologies": "NOT_MEASURED"
    },
    "direct_exposure": null,
    "indirect_exposure": null,
    "shadow_observations": []
  }
}
```
Consulte Como as regras decidem antes de automatizar a liberação. HTTP 200 com fail_closed: true e HOLD é uma análise registrada que exige retenção e reprocessamento; uma base de DENY continua prevalecendo.

Repetir a chamada com a mesma Idempotency-Key e os mesmos bytes devolve a mesma análise com idempotent_replay: true, sem registrar uso de novo. Para ver REVIEW, DENY e HOLD, troque o endereço pelo das outras fixtures.

Registrar a sua decisão

A decisão operacional e o desfecho de suspeição são seus e são registrados uma única vez. Escopo: vasp:transactions:screen.

curl -X PATCH "$SENTINEX_BASE_URL/vasp/screenings/0b8f3c2e-5a7d-4e61-9f2b-1c3d4e5f6a7b/client-decision" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_decision": {
      "operational_action": "ALLOW",
      "suspicion_outcome": "NOT_SUSPICIOUS",
      "rationale": "Teste de integração no sandbox."
    }
  }'

A segunda chamada para a mesma análise responde 409 com KYT_CLIENT_DECISION_ALREADY_RECORDED. O caminho antigo PATCH /vasp/screenings/{id}/decision está obsoleto.

Levar a integração para a produção
- Em produção, a chave não nasce na hora. Na conta real, Desenvolvedores > Chaves e uso da API > Nova API key registra um pedido; outro Tenant Admin do mesmo tenant aprova, e quem pediu emite a chave, que aparece uma única vez. Telas e detalhes no Guia de chaves de API
- Troque a chave por uma snxc_live_... e a base por https://crypto-api.sentinexrisk.com/api/v1. O restante da chamada não muda
- Na produção não há simulador: a contraparte é consultada de verdade, e a análise é real, gravada e auditada. Comece pela leitura do passo 3 e siga o roteiro de Homologação e testes
Próximos passos
- Resolver dúvidas operacionais: Dúvidas frequentes
- Receber eventos em vez de consultar: Webhooks
- Cadastrar clientes e carteiras: POST /vasp/customers e POST /vasp/wallets, no Guia de integração
- Todas as operações do contrato: referência da API
- Contrato em arquivo: openapi.yaml e openapi.json