# 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.

| Step | Order | Frequency | Result |
|  --- | --- | --- | --- |
| 1 | `v0_CreateAccount` intent | Once per account | Creates the account and derives its Ed25519 key and party ID. |
| 2 | `CreateParty` | Once per account | Allocates the party on your validator. |
| 3 | `CreateNativeTransferPreapproval` | Once per account | Lets the account receive Canton Coin directly. |
| 4 | `CreateTokenTransferPreapproval` | Once per account, for each CIP-56 token | Lets the account receive the token directly. |


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](/products/custody/accounts-and-assets/blockchains/canton/concepts#transfer-pre-approvals-and-two-step-transfers).

## Prerequisites

| Prerequisite | Additional information |
|  --- | --- |
| A registered Canton ledger | [Register the Canton ledger](/products/custody/accounts-and-assets/blockchains/canton/connect-your-validator#register-the-canton-ledger) |
| Registered tickers for Canton Coin and each CIP-56 token | [Register Canton Coin and CIP-56 tokens](/products/custody/accounts-and-assets/blockchains/canton/connect-your-validator#register-canton-coin-and-cip-56-tokens) |
| A vault ID | [List vaults](/products/custody/reference/api/openapi/vaults/getvaults) |
| New IDs in UUID format: an account ID, and a transaction order ID and intent ID for each order |  |


## Submit each order

System change process
All new requests to change the system state follow the same process. To familiarize yourself with this process first, see [Manage intents and approvals](/products/custody/governance/intents/manage-intents-and-approvals).

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](/products/custody/governance/intents/intent-request-structure#user-signed-proposal-request-body).
2. Call the [Perform a dry run for an intent](/products/custody/reference/api/openapi/intents/intentdryrun) operation, with the `request` field excluded. For more information, see [Dry run intents](/products/custody/governance/intents/manage-intents-and-approvals#dry-run-an-intent-with-the-api).
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](/products/custody/reference/api/openapi/intents/createintent) operation. For more information, see [Submit an intent with the API](/products/custody/governance/intents/manage-intents-and-approvals#submit-an-intent-with-the-api).
4. Check the intent status. For more information, see [Check state with the API](/products/custody/governance/intents/manage-intents-and-approvals#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](/products/custody/transactions/viewing-assets/view-and-audit-api).


## Step 1: Create the account

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.

```json
{
  "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](/products/custody/accounts-and-assets/accounts/manage-accounts-api#create-an-account-with-the-api).

## Step 2: Create the party

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.

```json
{
  "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](/products/custody/reference/api/openapi/accounts/getaddresses) operation, with `ledgerId` set to your Canton ledger ID and `lastOnly` set to `true`. The `address` value is the party ID:

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

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

The example shows the `address` field only.

## Step 3: Create the Canton Coin pre-approval

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.

```json
{
  "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"
  }
}
```

## Step 4: Create a pre-approval for each CIP-56 token

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

```json
{
  "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.

## Set up cold vault accounts

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](/products/custody/accounts-and-assets/blockchains/canton/send-and-receive-api#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](/products/custody/identity-and-access/vault-management/cold-vaults).

## Next steps

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](/products/custody/accounts-and-assets/blockchains/canton/send-and-receive-api).