Walrus Client

Using an agent? Try this prompt

Install the Walrus CLI, configure it for Testnet, and verify the setup by printing the current epoch and storage price.

Use the command-line interface (CLI) to interact with the Walrus client. The CLI is available by installing the walrus binary. To install Walrus, use the Mysten Labs suiup tool:

$ curl -sSfL https://raw.githubusercontent.com/Mystenlabs/suiup/main/install.sh | sh

Then install sui and walrus:

$ suiup install sui
$ suiup install walrus

View detailed usage information including a full list of available commands using the following command:

$ walrus --help

Each subcommand of walrus can also be called with --help to print its specific arguments and their meaning.

Switching contexts

If you have multiple contexts in your configuration file, you can specify the context for each command using the --context option. Generate a bash, zsh, or fish completion script with walrus completion and place it in an appropriate directory like ~/.local/share/bash-completion/completions.

Configuration

The Walrus client needs to know about the Sui objects that store the Walrus system and staking information. Configure these in the client_config.yaml file.

By default, the Walrus client looks for the client_config.yaml (or client_config.yml) configuration file in the current directory, $XDG_CONFIG_HOME/walrus/, ~/.config/walrus/, or ~/.walrus/.

Obtain the latest configuration file by downloading it directly from Walrus and placing it in one of the default configuration file locations:

$ curl --create-dirs https://docs.wal.app/setup/client_config.yaml -o ~/.config/walrus/client_config.yaml

You can place the file anywhere and name it anything you like. In that case, use the --config option when running the walrus binary.

Specify a wallet

Use the --wallet <WALLET> argument to specify a non-standard Sui wallet configuration file. The wallet configuration is taken from the path specified in the Walrus configuration, ./sui_config.yaml, or ~/.sui/sui_config/client.yaml.

Set a gas budget

Use the --gas-budget <GAS_BUDGET> argument to change the maximum amount of Sui (in MIST) that the command is allowed to use. If not specified, the gas budget is estimated automatically.

Print output as JSON

Use the --json flag to write a command's output as JSON. This is the default in JSON mode.

Example

You can access Testnet and Mainnet through the following configuration. This example Walrus CLI configuration refers to the standard location for Sui configuration (~/.sui/sui_config/client.yaml).

setup/client_config.yaml
contexts:
  mainnet:
    system_object: 0x2134d52768ea07e8c43570ef975eb3e4c27a39fa6396bef985b5abc58d03ddd2
    staking_object: 0x10b9d30c28448939ce6c4d6c6e0ffce4a7f8a4ada8248bdad09ef8b70e4a3904
    n_shards: 1000
    max_epochs_ahead: 53
    wallet_config:
      # Optional path to the wallet config file.
      # path: ~/.sui/sui_config/client.yaml
      # Sui environment to use.
      active_env: mainnet
      # Optional override for the Sui address to use.
      # active_address: 0x0000000000000000000000000000000000000000000000000000000000000000
    rpc_urls:
      - https://fullnode.mainnet.sui.io:443
  testnet:
    system_object: 0x6c2547cbbc38025cf3adac45f63cb0a8d12ecf777cdc75a4971612bf97fdf6af
    staking_object: 0xbe46180321c30aab2f8b3501e24048377287fa708018a5b7c2792b35fe339ee3
    exchange_objects:
      - 0xf4d164ea2def5fe07dc573992a029e010dba09b1a8dcbc44c5c2e79567f39073
      - 0x19825121c52080bb1073662231cfea5c0e4d905fd13e95f21e9a018f2ef41862
      - 0x83b454e524c71f30803f4d6c302a86fb6a39e96cdfb873c2d1e93bc1c26a3bc5
      - 0x8d63209cf8589ce7aef8f262437163c67577ed09f3e636a9d8e0813843fb8bf1
    n_shards: 1000
    max_epochs_ahead: 53
    wallet_config:
      # Optional path to the wallet config file.
      # path: ~/.sui/sui_config/client.yaml
      # Sui environment to use.
      active_env: testnet
      # Optional override for the Sui address to use.
      # active_address: 0x0000000000000000000000000000000000000000000000000000000000000000
    rpc_urls:
      - https://fullnode.testnet.sui.io:443
default_context: testnet

Acquire and move WAL

Storing data costs WAL, and every transaction costs SUI for gas. The walrus CLI exchanges SUI for WAL on Testnet. To move WAL between addresses, use sui client, because Sui handles the transfer rather than Walrus.

Exchange SUI for WAL on Testnet

Run walrus get-wal to exchange Testnet SUI for Testnet WAL at a 1:1 rate:

$ walrus get-wal --context testnet

The command exchanges 500,000,000 MIST (0.5 SUI) by default. These options change that behavior:

Option	What it does
`--amount <MIST>`	Exchanges the amount you pass, in MIST.
`--exchange-id <OBJECT_ID>`	Uses the exchange object you name instead of one picked from the configuration file. The option takes precedence over the configuration file.

For the full walkthrough, including how to confirm the balance afterwards, see Exchange Testnet SUI for WAL. The exchange object IDs are listed in the Network Reference.

Acquire WAL on Mainnet

walrus get-wal runs on Testnet only. The Mainnet context in the client configuration file declares no exchange objects, so the command fails there:

The object ID of an exchange object must be specified either in the config file or as a command-line argument.
Note that this command is only available on Testnet.

On Mainnet, acquire WAL on an exchange that lists the token, or receive a transfer from an address that already holds WAL. Avoid third-party WAL faucets: they can hand you WAL from a package the Walrus client rejects, and storage payments then fail.

Transfer WAL between addresses

Walrus has no transfer command. Sui holds WAL as a coin type, so sui client moves it. You need this when you fund a publisher wallet, a shared team wallet, or an agent wallet that stores blobs for you.

List the WAL coin objects an address holds. Read the fully qualified coin type, which ends in ::wal::WAL, from the coinType field of sui client balance --json:
```
$ sui client balance ADDRESS --coin-type WAL_COIN_TYPE --with-coins --json
```

Transfer one of those coin objects to the recipient:

$ sui client transfer --object-id WAL_COIN_ID --to RECIPIENT_ADDRESS --gas-budget 10000000

Sui transfers whole coin objects. To send an exact amount instead, split a coin in a programmable transaction block and transfer the coin object that the split produces. Amounts are in FROST, where 1 WAL = 1,000,000,000 FROST.

If an address holds many small WAL coins, merge them first so that a single coin covers the amount you want to send:

$ sui client merge-coin --primary-coin LARGEST_WAL_COIN_ID --coin-to-merge OTHER_WAL_COIN_ID

The recipient needs SUI for gas as well. WAL alone does not pay for transactions.

Logging and metrics

The walrus CLI supports multiple levels of logging, which you can toggle through an environment variable:

$ RUST_LOG=walrus=trace walrus info

By default, info level logs are enabled. The debug and trace levels can give a more in-depth understanding of what a command does or how it fails.

Switching contexts​

Configuration​

Specify a wallet​

Set a gas budget​

Print output as JSON​

Example​

Acquire and move WAL​

Exchange SUI for WAL on Testnet​

Acquire WAL on Mainnet​

Transfer WAL between addresses​

Logging and metrics​