Manage accounts with the API

Use this page for account operations with the Ripple Custody API. For UI procedures, see Manage accounts in the UI. For the account model, see Accounts.

Account changes use the standard intent flow. For signing, approval, and status checks, see Manage intents and approvals, Sign intents, and Check updates.

Create an account by submitting a v0_CreateAccount intent.

API reference:

POST /v1/intents/dry-run
POST /v1/intents

The examples in this section show the intent payload block. When you dry run or propose the intent, include this payload inside the standard request body with the intent ID in id for dry runs or request.id for signed proposals. For the full request shapes, see Intent request structure.

Before you create an account, prepare:

{
  "payload": {
    "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
    "alias": "btc-zero",
    "providerDetails": {
      "vaultId": "00000000-0000-0000-0000-000000000000",
      "keyStrategy": "VaultHard",
      "type": "Vault"
    },
    "ledgerIds": ["bitcoin-testnet"],
    "lock": "Unlocked",
    "description": "a bitcoin account for testing",
    "customProperties": {
      "testnet_account": "true"
    },
    "type": "v0_CreateAccount"
  }
}

Field notes:

Use account read operations to find account IDs, retrieve account details, and retrieve ledger addresses.

API reference:

GET /v1/domains/{domainId}/accounts
GET /v1/domains/{domainId}/accounts/{accountId}
GET /v1/domains/{domainId}/accounts/{accountId}/addresses/{accountAddressId}

1. If you do not know the account ID, call List accounts. You can filter accounts by criteria such as ledger ID.
2. Call Get account details with the account ID.
3. To retrieve a specific account address, call Retrieve account address.

Depending on the account type, account details include:

Multi-ledger account ledger statuses include:

Use v0_UpdateAccount to update mutable account details such as alias, description, and custom properties.

API reference:

POST /v1/intents/dry-run
POST /v1/intents

Submit an update intent with the current account reference:

{
  "payload": {
    "reference": {
      "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
      "revision": 2
    },
    "alias": "btc-zero",
    "description": "Updated account description",
    "customProperties": {},
    "type": "v0_UpdateAccount"
  }
}

Use v0_AddAccountLedgers to add compatible ledgers to an existing account.

API reference:

POST /v1/intents/dry-run
POST /v1/intents

Submit an add-ledgers intent with the current account reference:

{
  "payload": {
    "reference": {
      "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
      "revision": 2
    },
    "ledgerIds": ["ethereum-mainnet"],
    "type": "v0_AddAccountLedgers"
  }
}

Use v0_LockAccount when an account should not be used for outbound activity. Use v0_UnlockAccount only after confirming the account should be re-enabled.

API reference:

POST /v1/intents/dry-run
POST /v1/intents

{
  "payload": {
    "reference": {
      "id": "3b6d578e-7396-495d-8392-61b7ede174b3",
      "revision": 2
    },
    "type": "v0_LockAccount"
  }
}

Use v0_UnlockAccount with the same reference shape to re-enable the account.

Before you send assets, check the amount available to send. Balances depend on transaction state and ledger-specific behavior.

API reference:

GET /v1/domains/{domainId}/accounts/{accountId}/balances

Account balances include:

Call Get account balances.

An account can receive funds directly from the blockchain that are not registered automatically in Ripple Custody. For example, staking rewards might not be reflected until balances are refreshed.

API reference:

POST /v1/domains/{domainId}/accounts/{accountId}/balances/refresh

To force an account balance update, call Update account balances forcefully.

Use account-level compliance settings to control how incoming transfers are processed. The skipQuarantineFrom setting allows internal transfers to bypass quarantine screening. For more information, see Skip quarantine for internal transfers.

API reference:

GET /v1/domains/{domainId}/accounts/{accountId}/compliance-configuration
PUT /v1/domains/{domainId}/accounts/{accountId}/compliance-configuration
GET /v1/domains/{domainId}/compliance-configurations

Before configuring compliance settings, prepare:

To retrieve the current configuration for an account, call Get compliance configuration.

To create or update the configuration, call Set compliance configuration with the desired skipQuarantineFrom value and revision:

{
  "skipQuarantineFrom": "Domain",
  "revision": 1
}

Always retrieve the current configuration before updating so you can use the correct revision number. To disable skip quarantine, set skipQuarantineFrom to None.

To retrieve all compliance configurations in a domain, call List compliance configurations.

Before submitting an account-management intent:

• Confirm the target domain.
• Confirm the vault ID, key strategy, and ledger IDs.
• Confirm the policy that will govern the account intent.
• Dry run the payload.
• Verify the executed change by viewing account details.