Create an address

POST

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

POST

/api/rest/v1/addresses

curl -X POST https://your-protect-instance.example.com/api/rest/v1/addresses \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "walletId": "123456",
  "label": "Satoshi genesis address.",
  "comment": "The first bitcoin address.",
  "customerId": "7891011",
  "currency": "BTC"
}'

{
  "result": {
    "id": "987654321",
    "walletId": "123456",
    "seed": "btc",
    "currency": "BTC",
    "addressPath": "m/44'/0'/0'/0/0",
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "comment": "The first bitcoin address.",
    "label": "Satoshi genesis address - BTC",
    "customerId": "customer_7890",
    "balance": {},
    "signature": "XYZSignature",
    "creationDate": "2025-03-27T15:30:00.000000Z",
    "updateDate": "2025-03-27T15:30:00.000000Z",
    "walletInfo": {
      "id": "123456",
      "balance": {},
      "currency": "BTC",
      "coin": "BTC",
      "name": "Satoshi Wallet",
      "seed": "btc",
      "accountPath": "m/44'/0'/0'/0",
      "creationDate": "2025-03-27T15:30:00.000000Z",
      "updateDate": "2025-03-27T15:30:00.000000Z",
      "comment": "Collection of addresses used for long term savings. A wallet in Protect is simply a collection of addresses.",
      "blockchain": "BTC"
    }
  }
}

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

walletIdstringRequiredformat: "uint64"

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.

labelstringRequired

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

commentstringOptional

Optional comment for additional information about the address.

customerIdstringOptional

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

nonHardenedDerivationbooleanOptional

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

workchainIdintegerOptional

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

typestringOptional

Address type, specific to the blockchain being used. For BTC, valid values are p2pkh, p2sh_p2wpkh, or p2wpkh. For more information, contact support.

externalAddressIdstringOptional

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.

Response

A successful response.

resultobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

503

Service Unavailable Error