Vaults

Conceitos rápidos

• vault Carteira lógica controlada pelo sistema.

Uma vault é a unidade principal de custódia lógica da plataforma. Ela organiza fundos, endereços, saldos e transações dentro da mesma estrutura operacional.

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"
}

Observações

• A API precisa já ter uma master key criada.
• O vaultId funcional é gerado automaticamente.
• requestId é útil para rastrear chamadas feitas pelo cliente.

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
}

Observações

• O retorno já traz metadados de paginação.
• O vaultId usado em outras rotas costuma ser o identificador funcional, não o id interno.