Skip to content

External IDs

When creating vaults, wallets and transfers via the API, customers may create and assign an externalId to the request. The benefit of assigning a unique identifier to an API request is that it ensures the request is idempotent. An idempotent call or operation is one that produces the same result even if repeated many times.

In practice, this means that if a customer accidentally submits a Create Vault/Wallet/Transfer API request containing a particular externalID multiple times, Wallet-as-a-Service (Palisade) will recognise that the duplicate requests contain the same externalID and only process the first one.

Therefore, using an externalID provides protection against human error and unintended consequences. If an externalID is not used, there is no way for Wallet-as-a-Service (Palisade) to differentiate between deliberate and accidental requests and all the requests will be executed.

Example - Vaults

ExternalID may be used in the Create Vault request body as follows (see the Wallet-as-a-Service (Palisade) API for details):

{
    "name": "Treasury",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1"
}

This will result in a response similar to the following (containing the same externalId field):

{
    "id": "0195b3dd-5b95-7d89-8528-f22af192af39",
		...
    "name": "Treasury",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1",
    ...

Subsequent calls to the Create Vault API using the same externalId value will return the same Vault object.

Example - Wallets

ExternalID may be used in the Create Wallet request body as follows (see the Wallet-as-a-Service (Palisade) API for details):

{
    "name": "USD Issuance",
 		"blockchain": "AVALANCHE",
  	"keystore": "HSM",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1"
}

This will result in a response similar to the following (containing the same externalId field):

{
    "id": "0195b3dd-5b95-7d89-8528-f22af192af39",
		...
    "name": "USD Issuance",
 		"blockchain": "AVALANCHE",
  	"keystore": "HSM",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1",
    ...

Subsequent calls to the Create Wallet API using the same externalId value will return the same Wallet object.

Example - Transactions

ExternalID may be used in the Create Transfer request body as follows (see the Wallet-as-a-Service (Palisade) API for details):

{
    "destinationAddress": "rMhieePimPBNQZByxQxX1HXY6VyxEep2JE",
    "qty": "0.000003",
    "symbol": "XRP",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1"
}

This will result in a response similar to the following (containing the same externalId field):

{
    "id": "0195b3dd-5b95-7d89-8528-f22af192af39",
		...
    "status": "REQUESTED",
    "action": "PALISADE_TRANSFER",
    "externalId": "95a770cd-8766-4dd5-938c-3c10ead1c4b1",
    ...

Subsequent calls to the Create Transfer API using the same externalId value will return the same Transaction object.

Properties of externalId field

  • It is optional and nullable. Empty string value is treated as a null value.
  • It must be a minimum of 1 character and a maximum of 64 characters in length.
  • It must be unique and organization wide. This means that two wallets cannot have transactions containing the same externalId.
  • The API will create a new object for every request that has externalId set to null.