Create an address

post

https://your-protect-instance.example.com/api/rest/v1/addresses

This endpoint creates a new address within a specified Wallet. All addresses must be associated with a parent wallet. Addresses created with this endpoint are internal to Protect. To create an external address, you need to create a whitelisted address request.

For more information about whitelisted assets, see our user guides.

Address creation requires HSM signature, which makes it synchronous. Therefore, address creation can be slow, and failures may occur if the HSM is either unavailable or takes too long to process. If this happens, the API can be safely called again.

Required role: AccountCreator.

Body Params

walletId

string

required

Unique identifier for the wallet in which the address will be created. Must be an existing wallet ID. In Protect, a wallet represents a logical collection of addresses.

label

string

required

A human-readable label for the address. Displayed as Name in the UI.

comment

string

Optional comment for additional information about the address.

customerId

string

ID of the customer that owns the address. Automatically set if address belongs to an omnibus (shared) wallet.

nonHardenedDerivation

boolean

Indicates whether non-hardened derivation should be used for address creation. Default (recommended value) is false.

workchainId

int32

Workchain identifier. Used for smart contracts on blockchains like TON.

type

string

Address type, specific to the blockchain being used.

For BTC & LTC, valid values are p2pkh, p2sh_p2wpkh, or p2wpkh. Defaults to p2sh_p2wpkh if empty.

For DOGE, value must be p2pkh. Will default to p2pkh if empty.

For all other blockchains, this field must be empty.

externalAddressId

string

Identifier for the address in the user's system. This must be unique. Attempting to create an address with an existing externalAddressId will return the originally created address instead of creating a new one.

Responses

200A successful response.

400Bad Request: indicates that the server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing)

401Unauthorized: indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource

403Forbidden: indicates that the server understands the request but refuses to authorize it

404Not Found: indicates that the server cannot find the requested resource

500Internal Server Error: indicates that the server encountered an unexpected condition that prevented it from fulfilling the request

503Service Unavailable: indicates that the server is not ready to handle the request.

defaultAn unexpected error response.