Set up Sui with the API

To use Sui, add the Sui ledger, allowlist the tokens that you want to send, and create accounts on the ledger. Sui accounts don't need any ledger-specific setup: after you create an account, it can receive and send straight away.

Prerequisites

Prerequisite	Details
A Sui node connection	Your Customer Partner Engineer (CPE) sets up the connection between Ripple Custody and a Sui node. Contact your Ripple liaison to enable Sui.
Ledger accounting refactor phase 2	Phase 2 is active in your environment. Sui transactions use the refactored processing path. For more information, see Ledger accounting refactor phase 2.
New IDs in UUID format	An intent ID for each intent, and an account ID for each account.

Submit each intent

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.

For each intent on this page:

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.
Call the Perform a dry run for an intent operation, with the request field excluded. For more information, see Dry run an intent with the API.
Sign the request body and call the Propose an intent operation. For more information, see Submit an intent with the API.
Check the intent status. For more information, see Check state with the API.

Add the Sui ledger

Add each Sui network that you use as a ledger with a v0_CreateLedger intent. You can submit this intent only in the root domain.

{
  "payload": {
    "id": "sui",
    "alias": "Sui",
    "parameters": {
      "type": "Sui",
      "nativeTickerName": "Sui",
      "nativeTickerSymbol": "SUI"
    },
    "description": null,
    "customProperties": {},
    "type": "v0_CreateLedger"
  }
}

Field	Description
`id`	The ledger ID, which you choose, as for other ledgers. The standard payloads use `sui` and `sui-testnet`. For the payloads, see Dynamic ledger payloads.
`parameters.type`	`Sui`
`parameters.nativeTickerName`	The display name of the native currency.
`parameters.nativeTickerSymbol`	The symbol of the native currency.

For more information about adding ledgers, see Dynamic ledgers.

Allowlist Sui coins

Ripple Custody creates a token automatically the first time one of your addresses receives a coin type that it doesn't know yet. It reads the symbol, decimals, and coin type from the coin's on-chain metadata. To send the token, allowlist it first. For more information, see Allowlist tokens.

You can also allowlist a Sui coin before you receive it, with a v0_ValidateTickers intent. Set ledgerDetails.properties.type to Coin, and coinType to the coin's type tag. This example allowlists Circle USDC on Sui mainnet:

{
  "payload": {
    "tickers": [
      {
        "id": "4c2e8a1f-6b3d-4f9e-a5c7-2d8b1e4f7a3c",
        "ledgerId": "sui",
        "kind": "Token",
        "name": "USDC",
        "symbol": "USDC",
        "decimals": 6,
        "ledgerDetails": {
          "type": "Sui",
          "properties": {
            "type": "Coin",
            "coinType": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
          }
        },
        "lock": "Unlocked",
        "customProperties": {}
      }
    ],
    "type": "v0_ValidateTickers"
  }
}

Field	Description
`tickers[].decimals`	The coin's decimals, from its on-chain metadata.
`tickers[].ledgerDetails.type`	`Sui`
`tickers[].ledgerDetails.properties.type`	`Native` for SUI. `Coin` for any other Sui coin.
`tickers[].ledgerDetails.properties.coinType`	`Coin` only. The coin's Move type tag, in the form `0x<package>::<module>::<name>`, without generic type parameters.

Get each coin's type tag and decimals from its issuer or from a Sui explorer. Enter the type tag exactly. A wrong type tag registers a different coin.

Create an account

Create a Sui account with a v0_CreateAccount intent, and include your Sui ledger ID in ledgerIds. Ripple Custody derives the account's Ed25519 key in your vault, and the Sui address from its public key.

{
  "payload": {
    "id": "6e1b9d4f-2a7c-4e8b-b3f5-9c1d7a4e2b6f",
    "alias": "sui-treasury-01",
    "providerDetails": {
      "vaultId": "0b9e4d2f-6a1c-4e7b-8d3f-5c9a1e7b3d6f",
      "keyStrategy": "VaultHard",
      "type": "Vault"
    },
    "ledgerIds": ["sui"],
    "lock": "Unlocked",
    "description": "Sui treasury account",
    "customProperties": {},
    "type": "v0_CreateAccount"
  }
}

To get the account's Sui address, call the Retrieve latest external address operation, with ledgerId set to your Sui ledger ID. For more information about accounts, see Manage accounts with the API.

Next steps

Share the address with your counterparties, and start to send and receive. For more information, see Send and receive Sui assets with the API.