Send and receive Sui assets with the API

This page explains how to send and receive SUI and Sui coins. A Sui transfer is a v0_CreateTransactionOrder intent with parameters.type set to Sui, and your policies and approvals apply to it like any other transaction order.

Before you start, add the Sui ledger, allowlist your tokens, and create an account. For more information, see Set up Sui with the API.

Operations

Operation	Use it to
`NativeTransfer`	Send SUI.
`CoinTransfer`	Send any other Sui coin, identified by its coin type.

Send assets

To send assets, follow the steps in Send assets with the API, with a payload like the examples in this section.

We recommend a dry run before each order. The dry run returns the fee estimate, and for a regulated coin, it tells you if the recipient is on the coin's deny list.

Send SUI

This example sends 25 SUI:

{
  "payload": {
    "id": "8b3e1f7a-4c2d-4a9e-b6f1-5d8c2a7e3b9f",
    "accountId": "6e1b9d4f-2a7c-4e8b-b3f5-9c1d7a4e2b6f",
    "ledgerId": "sui",
    "parameters": {
      "type": "Sui",
      "operation": {
        "type": "NativeTransfer",
        "destination": {
          "type": "Address",
          "address": "0x7d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169677c1be02aaf0b58e"
        },
        "amount": "25000000000"
      },
      "feeStrategy": {
        "type": "Priority",
        "priority": "Low"
      },
      "maximumFee": "10000000"
    },
    "description": "SUI settlement to counterparty",
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

Send a Sui coin

A CoinTransfer takes the same fields as a NativeTransfer, plus the coin's coinType. This example sends 1,000 USDC with a validity window of 7 epochs:

{
  "payload": {
    "id": "2f9c6a3e-8d1b-4e5f-a7c2-4b9e1d6f3a8c",
    "accountId": "6e1b9d4f-2a7c-4e8b-b3f5-9c1d7a4e2b6f",
    "ledgerId": "sui",
    "parameters": {
      "type": "Sui",
      "operation": {
        "type": "CoinTransfer",
        "destination": {
          "type": "Address",
          "address": "0x7d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169677c1be02aaf0b58e"
        },
        "amount": "1000000000",
        "coinType": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
      },
      "feeStrategy": {
        "type": "Priority",
        "priority": "Low"
      },
      "maximumFee": "10000000",
      "validityEpochs": 7
    },
    "description": "USDC settlement to counterparty",
    "customProperties": {},
    "type": "v0_CreateTransactionOrder"
  }
}

Field	Description
`operation.destination`	The recipient. Use an `Address` destination with a Sui address, or another destination type, such as an endpoint or a Ripple Custody account.
`operation.amount`	The amount in the coin's smallest unit, as a string. For SUI, the unit is the MIST: 1 SUI is `"1000000000"`. For USDC, 1 USDC is `"1000000"`.
`operation.coinType`	`CoinTransfer` only. The coin's Move type tag. It must match an allowlisted token.
`parameters.feeStrategy`	Required. A `Priority` fee strategy with `Low`, `Medium`, or `High`. On Sui, the priority tier doesn't change the fee, but the API requires the field. We recommend `Low`.
`parameters.maximumFee`	Optional. The maximum fee, in MIST, that you accept.
`parameters.validityEpochs`	Optional. How many epochs, from 1 to 14, the transaction stays valid after preparation. If you omit it, Ripple Custody applies the network default.

Every Sui transaction pays its fee in SUI, including a CoinTransfer. Make sure that the sending account holds enough SUI to cover the gas budget.

Fees

The dry run returns the gas budget as fee, and the expected storageRebate. For the fields, see Transaction estimate. For how Sui fees work, see Gas and fees.

Validity window

Every Sui transaction expires at an epoch. An epoch lasts about 24 hours, so validityEpochs sets the window in days, roughly. For long approval flows or cold vault signing, set validityEpochs to cover your longest expected signing time, up to 14.

Ripple Custody fixes every transaction parameter, including the coins it spends and the gas price, when it prepares the transaction. The signed transaction stays valid for the whole window, however long signing takes, as long as the network's reference gas price doesn't rise.

Reference gas price changes

Sui sets a new reference gas price each epoch. If the reference gas price rises above the gas price that Ripple Custody fixed at preparation, the network can refuse the transaction before its window ends. The longer the window, the more epochs the transaction spans, and the higher the risk. If this happens, submit a new order.

When a transaction expires

If the network doesn't finalize a transaction before its expiration epoch, the network rejects it for good. Ripple Custody then marks the order as expired and releases its reserved coins and amount, so the account can transact again. To send the assets, submit a new order.

Sui doesn't support cancel and replace. You can't speed up a Sui transaction with a higher fee.

Transfers of regulated coins

For a regulated coin, such as Circle USDC, Ripple Custody checks the recipient against the coin's deny list before it builds the transaction:

A dry run returns an InvalidDestination failure with the reason.
A submitted order fails with InvalidDestination, and Ripple Custody broadcasts nothing.

The check includes deny list entries that are already in force and entries that take effect in the next epoch.

Receive assets

To receive assets, share the account's Sui address with the sender. To get the address, see Create an account.

Sui doesn't need any receive setup. Ripple Custody detects every transfer to your addresses, including transfers from applications and deposits to the address balance. Incoming assets then enter quarantine, like on every other ledger. For more information, see Receive assets.

Before you send a coin that you received for the first time, allowlist its token. For more information, see Allowlist Sui coins.

Balances and transaction history

Use the standard account and transaction operations for Sui accounts:

To view balances, see Check account balances. For what the balance includes, see Coin objects and balances.
To view history, see View and audit transactions with the API.

Ripple Custody emits the same events and webhooks for Sui transactions as for other ledgers. For more information, see Events and webhooks.