Verificação de carteira

Para que serve

A verificação de carteira comprova que um cliente final controla o endereço de autocustódia para onde quer sacar. Ela atende à exigência do art. 76-A, §5º da Resolução BCB 277/2022, com a redação dada pela Resolução BCB 521/2025.

O cliente assina uma mensagem com a própria carteira. A Clav confere a assinatura, guarda a prova e passa a responder, a cada saque, se aquele endereço está verificado.

Redes suportadas

O endereço é aceito com qualquer capitalização e normalizado para a forma canônica da rede antes de ser gravado. Use sempre o endereço que volta na resposta, não o que você enviou.

Como funciona

Pela plataforma, sem integração

Para um piloto, dá para usar sem escrever código. Em Carteiras verificadas, clique em Verificar carteira, preencha Identificador do cliente, Rede e Endereço, e clique em Criar link. Envie o link ao cliente pelo canal que você já usa com ele.

A tela tem duas abas: as carteiras já verificadas e os desafios aguardando assinatura. Ao abrir uma carteira, você vê a mensagem assinada, o método usado e a trilha completa de eventos.

Pela API

A integração usa a API REST em https://api.clav.tech/v1, autenticada com uma chave de API que tenha o escopo wallet:verify. O guia de chaves de API mostra como emitir uma. Todas as consultas ficam restritas à organização dona da chave.

Abrir um desafio

POST /v1/wallet-proofs
Authorization: Bearer <token>
Content-Type: application/json

{
  "externalCustomerId": "customer-8842",
  "chain": "EVM",
  "address": "0x5B38Da6a701c568545dCfcB03FcB875f56beddC4",
  "ttlSeconds": 600
}

ttlSeconds define por quanto tempo o desafio aceita assinatura, entre 60 e 86400 segundos. Sem ele, o prazo é de 600 segundos (10 minutos).

{
  "id": "65f0a1b2c3d4e5f60718293a",
  "nonce": "a3f1c0d9e8b7a6f5e4d3c2b1a0998877665544332211ffeeddccbbaa99887766",
  "message": "...",
  "expiresAt": "2026-09-16T12:10:00.000Z",
  "verificationUrl": "https://.../p/a3f1c0d9..."
}

Envie o cliente para verificationUrl. Se você mesmo for coletar a assinatura, exiba message exatamente como veio: um caractere diferente gera outra assinatura e a prova falha.

Acompanhar um desafio

GET /v1/wallet-proofs/{nonce}

O campo status passa por estes estados:

Um desafio que ninguém tentou assinar continua como PENDING mesmo depois do prazo. Para saber se ele ainda vale, compare expiresAt com o horário atual.

Um desafio aceita uma única assinatura. Se ela for recusada, abra um novo desafio. Para ser avisado sem precisar consultar, assine os webhooks wallet.verified e wallet.failed.

Consultar antes do saque

GET /v1/wallets?chain=EVM&address=0x5b38da6a701c568545dcfcb03fcb875f56beddc4

{
  "verified": true,
  "wallet": {
    "id": "65f0a1b2c3d4e5f60718293b",
    "chain": "EVM",
    "address": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
    "externalCustomerId": "customer-8842",
    "method": "SIGNATURE",
    "status": "ACTIVE",
    "challengeId": "65f0a1b2c3d4e5f60718293a",
    "verifiedAt": "2026-09-16T12:04:11.000Z",
    "revokedAt": null
  }
}

Libere o saque olhando apenas para verified. Ele só é true quando existe uma prova com status ACTIVE. Uma carteira revogada ainda aparece em wallet, mas com verified: false. Um endereço inválido para a rede também responde verified: false, sem erro HTTP.

Revogar uma carteira

POST /v1/wallets/{id}/revoke
Content-Type: application/json

{ "reason": "Ticket 4412: cliente removeu o endereço" }

A partir da resposta, a consulta passa a devolver verified: false e o cliente precisa provar o endereço de novo. A prova continua registrada, com status REVOKED, e o motivo vai para a trilha de auditoria.

Motivos de falha

Em ADDRESS_MISMATCH, a Clav guarda o endereço que de fato assinou. É um dado útil numa investigação de prevenção à lavagem de dinheiro.

Perguntas frequentes