> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Register wallet

> Non-custodial wallet registration. The caller provides the on-chain address,
the post-quantum public key, and a signature proving ownership. The custody
service verifies that the public key matches the address and that the signature
is valid over the deterministic challenge Keccak256('qustody:register:' + address).
The custody service never holds private keys.




## OpenAPI

````yaml POST /vault/accounts/{vaultAccountId}/wallets
openapi: 3.1.0
info:
  title: Qustody API
  description: >
    Non-custodial custody and orchestration API for Quantum Chain (post-quantum
    blockchain).

    Provides Fireblocks-like operating model for institutional integrators:

    multi-tenant vault/wallet management, transaction lifecycle with policy
    enforcement,

    external (callback-based) signing, webhook-driven event delivery, and full
    audit trail.
  version: 1.0.0
  contact:
    name: Quantum Chain Platform Team
  license:
    name: LGPL-3.0-or-later
servers:
  - url: '{baseUrl}/v1'
    description: Qustody API
    variables:
      baseUrl:
        default: https://api.qustody.io
security:
  - BearerAPIKey: []
tags:
  - name: health
    description: Liveness and readiness probes
  - name: tenants
    description: Tenant (integrator) management
  - name: vaults
    description: Vault (logical wallet grouping) management
  - name: wallets
    description: Wallet (on-chain address) registration and lookup
  - name: transactions
    description: Transaction lifecycle – create, sign, approve, reject, query
  - name: assets
    description: Supported asset registry
  - name: webhooks
    description: Webhook endpoint management
  - name: sso
    description: Single Sign-On (OIDC and SAML) authentication
  - name: tokens
    description: Token Management — Beta / Proposed.
paths:
  /vault/accounts/{vaultAccountId}/wallets:
    post:
      tags:
        - wallets
      summary: Register an external wallet address
      description: >
        Non-custodial wallet registration. The caller provides the on-chain
        address,

        the post-quantum public key, and a signature proving ownership. The
        custody

        service verifies that the public key matches the address and that the
        signature

        is valid over the deterministic challenge Keccak256('qustody:register:'
        + address).

        The custody service never holds private keys.
      operationId: registerWallet
      parameters:
        - name: vaultAccountId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterWalletRequest'
      responses:
        '201':
          description: Wallet registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
components:
  parameters:
    idempotencyKey:
      name: Idempotency-Key
      in: header
      schema:
        type: string
      description: Idempotency key for safe retries (required for POST/PUT)
  schemas:
    RegisterWalletRequest:
      type: object
      required:
        - assetId
        - address
        - publicKey
        - signature
      properties:
        assetId:
          type: string
          format: uuid
        address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        publicKey:
          type: string
          description: Hex-encoded post-quantum public key
          minLength: 3904
          maxLength: 3904
        signature:
          type: string
          description: >-
            Hex-encoded post-quantum signature over the ownership challenge:
            Keccak256('qustody:register:' + lowercase_address). Proves the
            caller controls the private key for the given address.
          minLength: 6586
          maxLength: 6586
        label:
          type: string
    Wallet:
      type: object
      required:
        - id
        - vaultId
        - tenantId
        - assetId
        - address
        - status
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        vaultId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        assetId:
          type: string
          format: uuid
        address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        publicKey:
          type: string
          description: Hex-encoded post-quantum public key
        label:
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - ARCHIVED
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    BearerAPIKey:
      type: http
      scheme: bearer
      description: 'API key authentication. Format: `Bearer {key_id}:{secret}`'

````