radius-cli

radius-cli is the canonical terminal surface for local Radius wallets and agent workflows. Use it to create or select a wallet, sign messages, check balances, send transactions, read contracts, inspect transactions, and consume x402-protected endpoints.

Use viem for application code. Use Foundry for smart contract builds, tests, and deployment scripts. Use radius-cli when an agent or terminal needs to operate a local Radius wallet.

Install and verify

Requires Node.js 20 or later.

Run one command with npx:

npx radius-cli --help

Or install the binary globally:

npm install -g radius-cli
command -v radius-cli
radius-cli --help

For x402 endpoint consumption, use radius-cli package version 0.1.4 or later. Verify that your installed binary exposes the x402 command:

radius-cli wallet x402 --help

Networks

radius-cli defaults to mainnet. Set the network explicitly in scripts and agent workflows.

RADIUS_NETWORK=testnet radius-cli wallet address

Override the RPC endpoint with --rpc-url or RADIUS_RPC_URL:

RADIUS_NETWORK=testnet RADIUS_RPC_URL={TESTNET_RPC_URL} radius-cli wallet balance

Project-scoped agent wallet

Use RADIUS_HOME to isolate wallet state per project, repo, or agent run:

export RADIUS_HOME=.radius
export RADIUS_NETWORK=testnet
export RADIUS_SBC_ADDRESS={FEE_CONTRACT}
 
radius-cli wallet address
radius-cli wallet balance --json

On first use, account-needing commands such as wallet address, wallet balance, wallet sign, and wallet send create a keystore in the configured Radius home. By default that is ~/.radius; with RADIUS_HOME=.radius, it is local to the current project.

To opt into a password before creating a wallet, set RADIUS_PASSWORD:

RADIUS_HOME=.radius RADIUS_NETWORK=testnet RADIUS_PASSWORD='use-a-secret-manager' radius-cli wallet new

Configuration precedence

radius-cli resolves configuration in this order:

1. CLI flags: --network, --rpc-url, --sbc, --rusd, --json, --private-key
2. Environment: RADIUS_NETWORK, RADIUS_RPC_URL, RADIUS_SBC_ADDRESS, RADIUS_RUSD_ADDRESS, RADIUS_PASSWORD, RADIUS_KEYSTORE_PATH, RADIUS_HOME
3. Radius config file in the active Radius home
4. Built-in defaults

Set RADIUS_SBC_ADDRESS or pass --sbc when using wallet balance or wallet send ... SBC.

Wallet commands

Create or import a wallet:

radius-cli wallet new
radius-cli wallet import 0xPRIVATE_KEY
radius-cli wallet address

Check balances:

RADIUS_HOME=.radius RADIUS_NETWORK=testnet RADIUS_SBC_ADDRESS={FEE_CONTRACT} \
  radius-cli wallet balance --json
 
radius-cli wallet balance 0x0000000000000000000000000000000000000000 --json

Sign and verify messages:

radius-cli wallet sign "hello"
echo -n "hello" | radius-cli wallet sign -
radius-cli wallet verify "hello" 0xSIGNATURE --address 0xSignerAddress

Send native RUSD:

RADIUS_HOME=.radius RADIUS_NETWORK=testnet \
  radius-cli wallet send 0xRecipientAddress 0.10 RUSD

Send SBC:

RADIUS_HOME=.radius RADIUS_NETWORK=testnet RADIUS_SBC_ADDRESS={FEE_CONTRACT} \
  radius-cli wallet send 0xRecipientAddress 0.10 SBC

Call an arbitrary state-changing contract function:

radius-cli wallet send 0xTokenAddress "transfer(address,uint256)" 0xRecipientAddress 100000

Use --json for machine-readable output and --no-wait when you only need the submitted transaction hash.

Read commands

Read a contract:

radius-cli call 0xTokenAddress "balanceOf(address)(uint256)" 0xWalletAddress

Inspect chain data:

radius-cli tx 0xTransactionHash --json
radius-cli receipt 0xTransactionHash --json
radius-cli storage 0xContractAddress 0
radius-cli code 0xContractAddress
radius-cli nonce 0xWalletAddress

Function signatures use cast-style syntax: name(args) for writes and name(args)(returns) for decoded reads.

x402 endpoint consumption

Use radius-cli wallet x402 <verb> <url> to request an x402-protected endpoint. If the endpoint responds with a payment challenge, the CLI signs and pays from the local wallet, then retries the request.

Agent-friendly GET request:

RADIUS_HOME=.radius RADIUS_NETWORK=testnet RADIUS_SBC_ADDRESS={FEE_CONTRACT} \
  radius-cli wallet x402 get https://example.com/protected \
  --x402-threshold 0.001 \
  --json \
  -y

POST with headers and JSON body:

RADIUS_HOME=.radius RADIUS_NETWORK=testnet RADIUS_SBC_ADDRESS={FEE_CONTRACT} \
  radius-cli wallet x402 post https://api.example.com/query \
  -H "Content-Type: application/json" \
  -d '{"query":"radius"}' \
  --x402-threshold 0.01 \
  --json \
  -y

Supported verbs are get, post, put, patch, delete, head, and options.

--x402-threshold is in display units for the payment asset, not raw integer units. For SBC, 0.01 means 0.01 SBC. Use it for non-interactive agent runs so the command refuses unexpectedly expensive requests.

Use -y only when the URL, network, and threshold are explicit. Use --json when another program or agent needs to parse the result. Use --include when you need response status and headers written alongside the response.

When to use other tools

Related pages

• Build with LLMs
• Create and Fund a Wallet
• Tooling configuration
• Network and RPC
• x402 integration