Pular para o conteúdo
Sentinex Risk Crypto

Triagem de carteira no onboarding

Cenário

Seção intitulada “Cenário”

O seu cliente declara uma carteira durante o onboarding. Você quer vincular a carteira ao cadastro dele, obter a triagem de risco dela e decidir o que fazer. Todos os passos usam operações do contrato do cliente, com X-API-Key.

  1. Vincular a carteira e obter a triagem

    POST /vasp/wallets valida o endereço pela rede, grava o endereço só cifrado e faz a triagem da carteira. Escopo: vasp:wallets:write.

    const resposta = await fetch('https://crypto-api.sentinexrisk.com/api/v1/vasp/wallets?mode=sync', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.SENTINEX_API_KEY,
        'Content-Type': 'application/json',
        'Idempotency-Key': chaveDaTentativa, // a mesma em toda retentativa
      },
      body: JSON.stringify({
        customer_id: idDoCliente, // devolvido por POST /vasp/customers
        external_id: 'carteira-do-cliente-42',
        address: enderecoDeclarado,
        blockchain: 'eth',
        asset_symbol: 'USDT',
        custody_type: 'self_hosted',
      }),
    });
    const envelope = await resposta.json();
    if (!envelope.success) throw new Error(`Vínculo recusado: ${JSON.stringify(envelope.error)}`);
    const carteira = envelope.data;
    Resposta Significado
    201 Carteira nova, com o resultado da triagem em data
    200 Carteira já conhecida do tenant, com o resultado armazenado (existing_wallet: true), ou replay idempotente
    202 Com mode=async: triagem aceita, screening_status: "PENDING" até o resultado
    400 Endereço inválido para a rede (invalid_wallet) ou corpo inválido
    409 Conflito, com o motivo em error.code: wallet_already_exists, wallet_is_institutional, wallet_address_active_elsewhere e outros

  2. Ler o resultado

    Os campos que decidem o próximo passo:

    Campo Valores
    decision APPROVE, REVIEW ou BLOCK
    screening_status PENDING, APPROVED, REVIEW, BLOCKED ou FAILED
    risk_score e risk_tier Score e faixa de risco da carteira
    reason_codes Motivos da triagem
    alert_created e alert_id Se a triagem abriu alerta na fila do tenant

    Com mode=async, consulte GET /vasp/wallets/{id} (escopo vasp:read) até screening_status sair de PENDING. Enquanto estiver pendente, trate a carteira como não liberada.

  3. Agir sobre o resultado

    function proximoPasso(carteira) {
      if (carteira.screening_status === 'PENDING' || carteira.screening_status === 'FAILED') {
        return 'AGUARDAR'; // sem resultado, a carteira não está liberada
      }
      switch (carteira.decision) {
        case 'APPROVE': return 'LIBERAR';
        case 'REVIEW':  return 'ANALISE_MANUAL';
        case 'BLOCK':   return 'RECUSAR';
        default:        return 'ANALISE_MANUAL';
      }
    }

    A regra acima é um exemplo: a decisão sobre o cliente é sua. Se a carteira deixar de ser usada, DELETE /vasp/wallets/{id} a desativa mantendo o mesmo wallet_id, e PATCH /vasp/wallets/{id} com status: "active" a reativa.

  4. Analisar as transações da carteira

    Cada depósito ou saque envolvendo a carteira passa por POST /vasp/screenings, como no Quickstart. A triagem da carteira no onboarding não substitui a análise de cada transação.

Eventos

Seção intitulada “Eventos”

Assinando os eventos em POST /vasp/webhooks, você recebe wallet.linked quando a carteira é vinculada ou reativada e wallet.deactivated quando é desativada. Os dois trazem wallet_id, customer_id, external_id e blockchain no payload. Ver Webhooks.