Hotwallets

Vaults

Esta secao descreve o conceito de vault dentro da Hotwallets e como ele organiza os fundos no sistema. A vault e a unidade principal de custodia logica, usada para separar operacoes, rastrear ativos e servir como origem para enderecos, saldos e transacoes.

Conceitos rápidos

  • vault Carteira lógica controlada pelo sistema.

Criar uma nova vault

Endpoint: POST /vaults

Serve para

Criar uma nova vault.

Autenticação

Exige bearer token com permissão vault:create.

Body

Todos os campos são opcionais.

{
  "name": "Treasury",
  "requestId": "uuid-opcional"
}

Retorno

{
  "requestId": "uuid",
  "id": "uuid",
  "vaultId": "12",
  "name": "Treasury",
  "status": "created",
  "createdAt": "2026-03-26T12:00:00.000Z"
}

Observacoes

  • A API precisa já ter uma master key criada.
  • O vaultId funcional é gerado automaticamente.

Listar vaults

Endpoint: GET /vaults

Serve para

Listar vaults com paginação e filtros.

Autenticação

Exige bearer token com permissão vault:read.

Query params

  • page Página atual. Padrão: 1.
  • pageSize Quantidade por página. Padrão: 10. Máximo: 100.
  • search Busca por vaultId, nome, requestId ou externalMasterKeyId.
  • status Filtra por status.

Retorno

{
  "items": [
    {
      "id": "uuid",
      "requestId": "uuid",
      "vaultId": "12",
      "name": "Treasury",
      "externalMasterKeyId": "mk_123",
      "externalVaultKeyId": null,
      "status": "created",
      "createdAt": "2026-03-26T12:00:00.000Z",
      "updatedAt": "2026-03-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1
}