POST /vasp/wallets

Cadastra carteira de cliente final com screening fail-closed

Vincula uma carteira a um cliente já cadastrado. mode=sync (default) responde 201 com o resultado do screening; mode=async responde 202 com status PENDING (fail-closed até o resultado). Carteira já conhecida da empresa responde 200 com o resultado armazenado. Suporta Idempotency-Key. Escopo exigido: vasp:wallets:write.

O endereço é validado pela rede (checksum EIP-55, bech32, base58 e afins) e gravado só cifrado, com o HMAC da empresa para igualdade; o endereço em claro e o prefixo não são armazenados. A busca da carteira existente cobre também as carteiras cadastradas antes da cifra, que são convertidas na mesma linha, sem duplicar. Carteira de cliente nunca é anexada a carteira institucional do mesmo endereço (409 wallet_is_institutional). custody_type é opcional; ausente fica registrado como não informado.

Item	Valor
Método	POST
Caminho	/vasp/wallets
URL	https://crypto-api.sentinexrisk.com/api/v1/vasp/wallets
Grupo	VASP - Carteiras
operationId	enrollVASPWallet
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
mode	query	string	não	Valores: sync, async. Padrão: sync.
Idempotency-Key	header	string	não	Mesma chave + corpo idêntico = replay idempotente (200 com idempotent_replay=true); mesma chave + corpo diferente = 409. Até 255 caracteres.

Corpo da requisição

Corpo obrigatório.

Tipo de mídia application/json.

Schema VASPWalletEnrollRequest, do tipo objeto.

Campo	Tipo	Obrigatório	Descrição
customer_id	string	sim	Id do cliente, no formato UUID, devolvido por POST /vasp/customers. Valor que não é UUID responde 400 invalid_wallet.
external_id	string	sim	Id da carteira no seu sistema (único por empresa). Até 128 caracteres.
address	string	sim	Endereço da carteira, validado pela rede (endereço inválido responde 400 invalid_wallet). O backend grava só a cifra do endereço e o HMAC da empresa; nunca o endereço em claro. Até 256 caracteres.
blockchain	string	sim	Aceitos: btc, eth, bsc, polygon, tron, solana, arbitrum (e aliases).
asset_symbol	string	não	Símbolo do ativo (A-Z, 0-9, ponto, underscore, hífen). Até 20 caracteres.
wallet_label	string	não	Até 255 caracteres.
custody_type	string	não	Custódia declarada pela VASP: vasp_custodied (a VASP custodia) ou self_hosted (autocustódia do cliente). Opcional: ausente fica registrado como não informado e é contado como tal. Valores: vasp_custodied, self_hosted.
metadata	objeto	não	JSON livre (máx. 16 KB), sem identificadores pessoais em claro.

Exemplo de chamada

curl -X POST "https://crypto-api.sentinexrisk.com/api/v1/vasp/wallets" \
  -H "X-API-Key: $SENTINEX_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -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	Carteira já existente vinculada, ou replay idempotente
201	Carteira nova cadastrada (mode=sync)
202	Carteira aceita para screening assíncrono (mode=async)

200

Carteira já existente vinculada, ou replay idempotente

Tipo de mídia application/json.

Tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	não
idempotent_replay	boolean	não
data	objeto (VASPWalletEnrollment)	não	Resposta dos endpoints de enrollment de carteira.
data.wallet_id	string (uuid)	não
data.customer_id	string	não
data.external_id	string	não
data.blockchain	string	não
data.asset_symbol	string	não
data.wallet_label	string	não
data.screening_status	string	não	PENDING, APPROVED, REVIEW, BLOCKED ou FAILED.
data.decision	string	não	Valores: APPROVE, REVIEW, BLOCK.
data.risk_score	number (float)	não
data.risk_tier	string	não
data.reason_codes	lista de string	não
data.existing_wallet	boolean	não	true quando a carteira já existia na base da empresa.
data.status_url	string	não	Caminho para consultar o status (GET /vasp/wallets/{id}).
data.alert_id	string	não
data.alert_created	boolean	não
data.status	string	não	Estado da carteira; a desativada mantém o wallet_id. Valores: active, deactivated.
data.custody_type	string ou null	não	Custódia declarada; null quando não informada. Valores: vasp_custodied, self_hosted.
data.deactivated_at	string (date-time) ou null	não

201

Carteira nova cadastrada (mode=sync)

Tipo de mídia application/json.

Tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	não
data	objeto (VASPWalletEnrollment)	não	Resposta dos endpoints de enrollment de carteira.
data.wallet_id	string (uuid)	não
data.customer_id	string	não
data.external_id	string	não
data.blockchain	string	não
data.asset_symbol	string	não
data.wallet_label	string	não
data.screening_status	string	não	PENDING, APPROVED, REVIEW, BLOCKED ou FAILED.
data.decision	string	não	Valores: APPROVE, REVIEW, BLOCK.
data.risk_score	number (float)	não
data.risk_tier	string	não
data.reason_codes	lista de string	não
data.existing_wallet	boolean	não	true quando a carteira já existia na base da empresa.
data.status_url	string	não	Caminho para consultar o status (GET /vasp/wallets/{id}).
data.alert_id	string	não
data.alert_created	boolean	não
data.status	string	não	Estado da carteira; a desativada mantém o wallet_id. Valores: active, deactivated.
data.custody_type	string ou null	não	Custódia declarada; null quando não informada. Valores: vasp_custodied, self_hosted.
data.deactivated_at	string (date-time) ou null	não

202

Carteira aceita para screening assíncrono (mode=async)

Tipo de mídia application/json.

Tipo objeto.

Campo	Tipo	Obrigatório	Descrição
success	boolean	não
data	objeto (VASPWalletEnrollment)	não	Resposta dos endpoints de enrollment de carteira.
data.wallet_id	string (uuid)	não
data.customer_id	string	não
data.external_id	string	não
data.blockchain	string	não
data.asset_symbol	string	não
data.wallet_label	string	não
data.screening_status	string	não	PENDING, APPROVED, REVIEW, BLOCKED ou FAILED.
data.decision	string	não	Valores: APPROVE, REVIEW, BLOCK.
data.risk_score	number (float)	não
data.risk_tier	string	não
data.reason_codes	lista de string	não
data.existing_wallet	boolean	não	true quando a carteira já existia na base da empresa.
data.status_url	string	não	Caminho para consultar o status (GET /vasp/wallets/{id}).
data.alert_id	string	não
data.alert_created	boolean	não
data.status	string	não	Estado da carteira; a desativada mantém o wallet_id. Valores: active, deactivated.
data.custody_type	string ou null	não	Custódia declarada; null quando não informada. Valores: vasp_custodied, self_hosted.
data.deactivated_at	string (date-time) ou null	não

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	Corpo JSON ilegível (texto em error), ou campos, mode ou Idempotency-Key inválidos (invalid_wallet, invalid_mode, invalid_idempotency_key).
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, nesta ordem de camadas: o escudo de borda recusa travessia de diretório na URL (ErroTexto); a chave é recusada pelo IP de origem (api_key_ip_not_allowed); o ambiente da chave não é aceito por esta implantação (api_key_environment_required ou api_key_environment_not_allowed); a conta não pode usar a API (TenantAccessRefusalResponse: empresa_SUSPENDED, empresa_NOT_OPERATIONAL, API_ACCESS_DISABLED ou empresa_ACCESS_DENIED); a chave não tem o escopo da rota (insufficient_scope, com o escopo na mensagem). Não repita sem corrigir a causa.
404	Cliente da carteira inexistente nesta empresa (texto em error). Com chave válida, route_not_found diz que o caminho ou o método não corresponde a operação servida (ErrorResponseCoded).
409	Endereço, external_id ou Idempotency-Key já existem (wallet_already_exists, KYT_IDEMPOTENCY_CONFLICT); o endereço é de carteira institucional da empresa (wallet_is_institutional); ou o endereço casa mais de uma carteira antiga (wallet_duplicate_legacy, com error.wallet_ids: desative as duplicatas por DELETE e reenvie).
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.
503	API de cadastro indisponível ou cifra do endereço indisponível; nenhuma carteira foi gravada. 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

Corpo JSON ilegível (texto em error), ou campos, mode ou Idempotency-Key inválidos (invalid_wallet, invalid_mode, invalid_idempotency_key).

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, ErroTexto.

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: ErroTexto

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

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, nesta ordem de camadas: o escudo de borda recusa travessia de diretório na URL (ErroTexto); a chave é recusada pelo IP de origem (api_key_ip_not_allowed); o ambiente da chave não é aceito por esta implantação (api_key_environment_required ou api_key_environment_not_allowed); a conta não pode usar a API (TenantAccessRefusalResponse: empresa_SUSPENDED, empresa_NOT_OPERATIONAL, API_ACCESS_DISABLED ou empresa_ACCESS_DENIED); a chave não tem o escopo da rota (insufficient_scope, com o escopo na mensagem). Não repita sem corrigir a causa.

Resposta compartilhada ErroAcessoNegado do contrato.

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, TenantAccessRefusalResponse, ErroTexto.

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

404

Cliente da carteira inexistente nesta empresa (texto em error). Com chave válida, route_not_found diz que o caminho ou o método não corresponde a operação servida (ErrorResponseCoded).

Tipo de mídia application/json.

Tipo um de: ErrorResponseCoded, ErroTexto.

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: ErroTexto

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

409

Endereço, external_id ou Idempotency-Key já existem (wallet_already_exists, KYT_IDEMPOTENCY_CONFLICT); o endereço é de carteira institucional da empresa (wallet_is_institutional); ou o endereço casa mais de uma carteira antiga (wallet_duplicate_legacy, com error.wallet_ids: desative as duplicatas por DELETE e reenvie).

Tipo de mídia application/json.

Schema VASPWalletErrorResponse, do tipo objeto.

Envelope de erro da superfície de carteiras VASP. Além de code e message, os conflitos de carteira trazem os ids envolvidos.

Campo	Tipo	Obrigatório	Descrição
success	boolean	sim	Exemplo: false.
error	objeto	sim
error.code	string	sim	Código estável. Na superfície de carteiras: wallet_already_exists, KYT_IDEMPOTENCY_CONFLICT, wallet_is_institutional, wallet_duplicate_legacy, wallet_has_open_process, wallet_address_active_elsewhere. Trate código desconhecido como erro genérico: a lista pode crescer.
error.message	string	sim
error.wallet_ids	lista de string (uuid)	não	Carteiras antigas que casam o endereço (wallet_duplicate_legacy).
error.wallet_id	string (uuid)	não	A outra carteira ativa do endereço (wallet_address_active_elsewhere).
error.case_ids	lista de string (uuid)	não	Casos abertos ligados à carteira (wallet_has_open_process).
error.sar_ids	lista de string (uuid)	não	SAR não enviados ligados à carteira (wallet_has_open_process).

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

503

API de cadastro indisponível ou cifra do endereço indisponível; nenhuma carteira foi gravada. 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.

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.