---
title: "Register an external wallet address"
method: POST
path: "/vault/accounts/{vaultAccountId}/wallets"
tags: ["wallets"]
---

# Register an external wallet address

`POST /vault/accounts/{vaultAccountId}/wallets`

## Request

- Base URL: `https://api.qustody.io/v1`
- URL: `https://api.qustody.io/v1/vault/accounts/{vaultAccountId}/wallets`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/quantum-chain-pte-ltd/apis/qustody-api/docs/vault/accounts/:vaultAccountId/wallets/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `vaultAccountId` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- RegisterWalletRequest
  - `assetId` string, uuid, required
  - `address` string, required
  - `publicKey` string, required: Hex-encoded post-quantum public key
  - `signature` string, required: 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.
  - `label` string

## Response `201`

Wallet registered

- Wallet
  - `id` string, uuid, required
  - `vaultId` string, uuid, required
  - `tenantId` string, uuid, required
  - `assetId` string, uuid, required
  - `address` string, required
  - `publicKey` string: Hex-encoded post-quantum public key
  - `label` string
  - `status` 'ACTIVE' | 'ARCHIVED', required
  - `createdAt` string, date-time, required

## Changes

- **2026-03-20** `85c86d562df2`: 1 breaking
  - added the new required request property `signature`
- **2026-03-19** `82dff8901b0c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/quantum-chain-pte-ltd/apis/qustody-api/changes/vault/accounts/:vaultAccountId/wallets/post.md)

---

[API](https://skmtc.dev/quantum-chain-pte-ltd/apis/qustody-api.md) - [All operations](https://skmtc.dev/quantum-chain-pte-ltd/apis/qustody-api/llms.txt) - [OpenAPI document](https://skmtc.dev/quantum-chain-pte-ltd/apis/qustody-api/revisions/ecb2cea3c096?raw)