POST /admin/blocklist

A blocklist do tenant é genérica por entidade, e não uma coleção pendurada na wallet. A rota recebe o par entity_type mais entity_value, e wallet é um dos tipos aceitos.

Listar

GET /api/v1/admin/blocklist?entity_type=WALLET&limit=100
Authorization: Bearer $SENTINEX_JWT

Adicionar

POST /api/v1/admin/blocklist
Authorization: Bearer $SENTINEX_JWT
Content-Type: application/json

{
  "entity_type": "WALLET",
  "entity_value": "bc1qexample0demoaddress0000000000000000",
  "reason": "Exposição confirmada a mixer acima de 80% em 30 dias",
  "severity": "HIGH",
  "expires_at": null
}

Campo	Obrigatório	Regra
`entity_type`	sim	`WALLET`, `CPF`, `CNPJ`, `IP` ou `EMAIL`. Outro valor retorna `400`. Device não entra por esta rota
`entity_value`	sim	Validado conforme o tipo. `CPF` e `CNPJ` são normalizados antes de gravar
`reason`	sim	De 5 a 500 caracteres, e não pode conter o próprio valor bloqueado nem PII
`severity`	não	`CRITICAL`, `HIGH`, `MEDIUM` ou `LOW`. Default `HIGH`
`expires_at`	não	ISO 8601 no futuro, ou `null` para permanente. Data passada retorna `400`

Como o valor é guardado

IP é gravado em coluna nativa. Os demais tipos gravam SHA-256 do valor, e a resposta devolve apenas um entity_hint mascarado (primeiros 6 caracteres, reticência, últimos 4), nunca o valor em claro. Não conte com a leitura de volta do endereço ou do documento.

Response 201

{
  "success": true,
  "data": {
    "id": "9c2a1b3e-1d0a-4b7f-8e2c-7a1b3c5d7e9f",
    "tenant_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "entity_type": "WALLET",
    "entity_hint": "bc1qex…0000",
    "source": "MANUAL",
    "reason": "Exposição confirmada a mixer acima de 80% em 30 dias",
    "severity": "HIGH",
    "added_by": "analista@suaempresa.com.br",
    "is_active": true,
    "expires_at": null,
    "created_at": "2026-05-18T14:32:11Z",
    "updated_at": "2026-05-18T14:32:11Z"
  }
}

Remover

A remoção é por id da entrada, e não por id da wallet, e exige justificativa no corpo.

DELETE /api/v1/admin/blocklist/{entry_id}
Authorization: Bearer $SENTINEX_JWT
Content-Type: application/json

{ "reason": "Nova triagem retornou risco baixo" }

O motivo segue a mesma regra de 5 a 500 caracteres, sem PII. Sem motivo válido, a resposta é 400.

Response 200

{ "success": true }

Bloqueio por carteira

Diferente da blocklist genérica acima, esta superfície opera sobre uma carteira já cadastrada, identificada pelo id (UUID) dela, e não pelo endereço on-chain. Mesmo papel e mesma exigência de MFA recente.

POST /api/v1/wallets/{id}/blocklist
Authorization: Bearer $SENTINEX_JWT
Content-Type: application/json

{ "reason": "Exposição confirmada a mixer acima de 80% em 30 dias" }

O corpo é opcional: requisição sem corpo bloqueia a carteira sem justificativa registrada. Corpo presente e ilegível retorna 400, para que um bloqueio nunca entre na trilha de auditoria com motivo vazio por erro de serialização.

Response 200

{
  "success": true,
  "message": "Carteira bloqueada. As operações com esta carteira passam a ser barradas.",
  "enforced": true
}

Erros específicos desta rota

Código	Quando
`404`	A carteira não existe ou não pertence ao seu tenant
`409`	A carteira não tem endereço on-chain registrado. O bloqueio seria apenas visual, porque o caminho de decisão da transação consulta o endereço, então ele é recusado antes de qualquer alteração. Conclua a triagem da carteira antes de bloquear
`503`	Trilha de auditoria indisponível. A alteração é revertida e a operação é cancelada

Desbloquear

DELETE /api/v1/wallets/{id}/blocklist
Authorization: Bearer $SENTINEX_JWT

Contrapartida do bloqueio, com o mesmo papel, a mesma exigência de MFA recente e a mesma regra de auditoria: sem trilha registrada, a remoção da restrição é cancelada.