Set up Canton accounts with the API

A new Canton account can't send or receive assets until you complete a one-time setup. You submit each setup step as a transaction order, which goes through your policies and approvals like any other order.

Complete all four steps before you share the account's party ID with counterparties. If a sender transfers to a party that doesn't exist yet, the transfer fails. If a sender transfers an asset that the account has no pre-approval for, the transfer becomes a two-step offer that you need to accept. For background, see Transfer pre-approvals and two-step transfers.

For each step on this page:

1. Prepare the request body in the standard intent proposal format, with the payload block shown for the step. For more information, see User-signed proposal request body.

2. Call the Perform a dry run for an intent operation, with the request field excluded. For more information, see Dry run intents.

   This step is optional, but we recommend it. A dry run shows errors before you submit. It also returns a fee estimate, which is always 0 on Canton.

3. Sign the request body and call the Propose an intent operation. For more information, see Submit an intent with the API.

4. Check the intent status. For more information, see Check state with the API.

5. Wait until the transaction reaches the Confirmed status before you submit the next step. For more information, see View and audit transactions with the API.

Create the account with a v0_CreateAccount intent, and include your Canton ledger ID in ledgerIds. Ripple Custody derives an Ed25519 key for the account in your vault, and the party ID from the key's public key.

{
  "payload": {
    "id": "3f7c1a9e-5b2d-4c8f-a6e1-9d3b7f5c2a8e",
    "alias": "canton-treasury-01",
    "providerDetails": {
      "vaultId": "0b9e4d2f-6a1c-4e7b-8d3f-5c9a1e7b3d6f",
      "keyStrategy": "VaultHard",
      "type": "Vault"
    },
    "ledgerIds": ["canton-mainnet"],
    "lock": "Unlocked",
    "description": "Canton treasury account",
    "customProperties": {},
    "type": "v0_CreateAccount"
  }
}

For more information about account fields, see Create an account with the API.

Submit a CreateParty order. Ripple Custody generates the party's topology transactions on your validator, the vault checks them against the account's key and signs them, and your validator allocates the party.

{
  "payload": {
    "id": "c2e8a4f6-1b3d-4a7c-9e5f-7d1b3a5c8e2f",
    "accountId": "3f7c1a9e-5b2d-4c8f-a6e1-9d3b7f5c2a8e",
    "ledgerId": "canton-mainnet",
    "parameters": {
      "type": "Canton",
      "operation": {
        "type": "CreateParty"
      }
    },
    "description": "Create Canton party",
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

After the order reaches the Confirmed status, get the account's party ID with the Retrieve all generated addresses operation, with ledgerId set to your Canton ledger ID and lastOnly set to true. The address value is the party ID:

GET /v1/domains/{domainId}/accounts/{accountId}/addresses?ledgerId=canton-mainnet&lastOnly=true

{
  "address": "c::12206ffe88de2bcb7db26414da9bce096f73c6f681cbdaa1a8747192bd1c46cec0a5"
}

The example shows the address field only.

Submit a CreateNativeTransferPreapproval order. Ripple Custody creates a Canton Coin pre-approval proposal. Your validator accepts the proposal and then renews the pre-approval automatically, so you don't need to extend it.

{
  "payload": {
    "id": "e5a1c7f3-9d2b-4e6a-8c4f-2b7d9e1a5c3f",
    "accountId": "3f7c1a9e-5b2d-4c8f-a6e1-9d3b7f5c2a8e",
    "ledgerId": "canton-mainnet",
    "parameters": {
      "type": "Canton",
      "operation": {
        "type": "CreateNativeTransferPreapproval"
      }
    },
    "description": "Pre-approve incoming Canton Coin",
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

Submit a CreateTokenTransferPreapproval order for each CIP-56 token that the account receives. Set tickerId to the token's ticker ID.

{
  "payload": {
    "id": "a9d3f7b1-4c6e-4a2d-b8f5-3e1c7a9d5b2f",
    "accountId": "3f7c1a9e-5b2d-4c8f-a6e1-9d3b7f5c2a8e",
    "ledgerId": "canton-mainnet",
    "parameters": {
      "type": "Canton",
      "operation": {
        "type": "CreateTokenTransferPreapproval",
        "tickerId": "8e4b2d6f-1a3c-4f7e-b9d2-6c8a0e2f4b7d"
      }
    },
    "description": "Pre-approve incoming CIP-56 token",
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

When you start to hold a new CIP-56 token, register its ticker, and then submit a CreateTokenTransferPreapproval order for each account that receives it.

The setup steps are the same for accounts in a cold vault. The difference is timing. Canton accepts a prepared transaction for 24 hours, so preparing, signing, and executing each order must fit in one 24-hour window. For more information, see Signing window.

Approvals don't create anything on the network, so your approval flow can take as long as it needs. Approve first, and prepare late: plan the cold vault signing session so that it follows preparation within 24 hours. If signing takes longer, the network rejects the prepared transaction, and you must submit the order again.

To keep cold vault accounts working smoothly:

• Plan the four setup steps as one signing session where you can. Because each step depends on the previous one, submit and sign them in order.
• Create a pre-approval for every asset that the account receives, before you share the party ID. With pre-approvals in place, incoming transfers settle directly and never need a cold vault signature.
• Avoid two-step transfer offers to cold vault accounts. Each Accept or Reject needs a cold vault signature within the 24-hour signing window, and the offer can also reach its executeBefore deadline before you sign it.

For more information about cold vaults, see Cold vaults.

After the setup is complete, share the party ID with your counterparties and start to send and receive. For more information, see Send and receive Canton assets with the API.