sauce wallet

sauce wallet manages the wallet directory: the encrypted keys that --wallet <name> signs with.

Synopsis

sauce wallet <verb> [options]
sauce wallet new <name> [--solana] [--password-env <NAME> | --password-file <path> | --password-command <command>]
sauce wallet list [--wallets <dir>] [--json]
sauce wallet address <name> [--wallets <dir>] [--json]
sauce wallet import <name> <file | -> [--solana] [password source]
sauce wallet export <name> [password source]

Description

A wallet is one key that the sauce command keeps in the wallet directory, ~/.sauce/wallets by default, encrypted under a password. Every command that signs takes --wallet <name> with the same password source, on EVM chains and on Solana. The local MCP server signs with these wallets too when it runs over stdio (MCP wallets).

Verb	What it does
`new`	Creates a wallet with a fresh key, encrypted under its password
`list`	Lists every wallet: its name, kind and address
`address`	Prints one wallet’s address. No password is needed
`import`	Stores a key you already have: a private key, a keystore or a Solana keypair
`export`	Shows a wallet’s key on your terminal, after you type the wallet’s name

Files. Each wallet is one file, <name>.json, written once with mode 0600 and never overwritten. The directory is created with mode 0700. An EVM wallet is a Web3 Secret Storage v3 keystore (scrypt, AES-128-CTR), so --keystore, cast wallet and geth read it. A Solana wallet is the same envelope around the 64-byte keypair, marked "kind": "solana". The file holds the address in the clear, so list and address need no password. Wallets, passwords and spending policy describes the format.
Names. A name is up to 64 characters of lowercase letters, digits, - and _, starting with a letter or a digit. A name already in the directory is refused.
Passwords. The password comes from exactly one source: --password-env <NAME>, --password-file <path> or --password-command <command>. With none of them, the command asks at the terminal, twice for a new wallet. A password is at least 8 characters. No option takes the password itself as its value.
Import. import reads the key from a file, or from stdin with -, never from the command line; an operand that looks like a key is refused. It takes an EVM private key (32 bytes of hex), a Web3 Secret Storage keystore (opened with the password, which the wallet then keeps), or a Solana keypair (the JSON array of 64 bytes that solana-keygen writes, or its base58).
Export. export writes the key to the terminal device itself, never to stdout. It asks you to type the wallet’s name first. With no controlling terminal it refuses; a pseudo-terminal counts as one. The MCP server has no tool for it.
Policy. A file <name>.policy.json beside a wallet limits what it sends through --wallet and the MCP server’s wallet tools, not through --keystore (spending policy). list marks each wallet that has one and prints a warning for a policy file that does not parse or that others can write.

These are hot wallets: whoever holds a wallet’s file and its password holds the key. Keep small balances in them. Agents, wallets and keys covers what an agent running as you can do with them.

Options

Option	Description
`--wallets [<dir>]`	The wallet directory. Default: `~/.sauce/wallets`
`--json`	Print one JSON object instead of text
`-h, --help`	Show the help
`--no-update-check`	Print no notice of a newer `sauce`, and read no registry for one

sauce wallet new

Option	Description
`--solana`	Create a Solana keypair. Default: an EVM key
`--wallets [<dir>]`	The wallet directory. Default: `~/.sauce/wallets`
`--password-env <NAME>`	The password is the environment variable `NAME`; no other variable is read
`--password-file <path>`	Or the contents of a file only you can read. Without a source, the password is asked for
`--password-command <command>`	Or what this command prints, such as a secret manager’s CLI
`--json`	Print one JSON object instead of text
`-h, --help`	Show the help
`--no-update-check`	Print no notice of a newer `sauce`, and read no registry for one

sauce wallet list

Option	Description
`--wallets [<dir>]`	The wallet directory. Default: `~/.sauce/wallets`
`--json`	Print one JSON object instead of text
`-h, --help`	Show the help
`--no-update-check`	Print no notice of a newer `sauce`, and read no registry for one

sauce wallet address

Option	Description
`--wallets [<dir>]`	The wallet directory. Default: `~/.sauce/wallets`
`--json`	Print one JSON object instead of text
`-h, --help`	Show the help
`--no-update-check`	Print no notice of a newer `sauce`, and read no registry for one

sauce wallet import

Option	Description
`--solana`	Refuse anything but a Solana keypair
`--wallets [<dir>]`	The wallet directory. Default: `~/.sauce/wallets`
`--password-env <NAME>`	The password is the environment variable `NAME`; no other variable is read
`--password-file <path>`	Or the contents of a file only you can read. Without a source, the password is asked for
`--password-command <command>`	Or what this command prints, such as a secret manager’s CLI
`--json`	Print one JSON object instead of text
`-h, --help`	Show the help
`--no-update-check`	Print no notice of a newer `sauce`, and read no registry for one

sauce wallet export

Option	Description
`--wallets [<dir>]`	The wallet directory. Default: `~/.sauce/wallets`
`--password-env <NAME>`	The password is the environment variable `NAME`; no other variable is read
`--password-file <path>`	Or the contents of a file only you can read. Without a source, the password is asked for
`--password-command <command>`	Or what this command prints, such as a secret manager’s CLI
`-h, --help`	Show the help
`--no-update-check`	Print no notice of a newer `sauce`, and read no registry for one

Output

new and import print the wallet’s name, kind, address, file and policy on stdout, and notes on stderr: the password source to sign with, that --keystore and cast wallet read an EVM wallet’s file, and that it is a hot wallet. list prints one line per wallet. address prints the address alone: a 0x address, or a base58 public key for a Solana wallet. With --json, new, import and address print one wallet, and list prints the directory and its wallets:

{
  "name": "agent",
  "kind": "evm",
  "address": "0xE1Eff146a8463ad592014Bd9cc0D058307364916",
  "path": "wallets/agent.json",
  "policy": "wallets/agent.policy.json"
}

policy is null for a wallet with no policy file. Exit codes: 0 on success; 1 when the command refuses, for example a name already taken, a password file others can read, or export with no terminal; 2 for a usage error, such as an invalid name, a password under 8 characters, or a key given on the command line.

Examples

The examples run in one directory in order. They keep their wallets in ./wallets with --wallets ./wallets, and read the password from pw.txt, a file with mode 0600, or from the variable SAUCE_WALLET_PASSWORD.

Create an EVM wallet

sauce wallet new agent --wallets ./wallets --password-file pw.txt

Its key is encrypted under the password from --password-file pw.txt: sign with --wallet agent and the same password source.
The file is a keystore: --keystore wallets/agent.json and cast wallet read it too.
This is a hot wallet: whoever holds its file and its password holds the key. Keep only small balances in it.
Created wallet agent (EVM): 0xE1Eff146a8463ad592014Bd9cc0D058307364916
  file    wallets/agent.json
  policy  none (wallets/agent.policy.json would set limits)

The first three lines are stderr.

Create a Solana wallet with the password from the environment

sauce wallet new agent-sol --solana --wallets ./wallets --password-env SAUCE_WALLET_PASSWORD

Its key is encrypted under the password from --password-env SAUCE_WALLET_PASSWORD: sign with --wallet agent-sol and the same password source.
This is a hot wallet: whoever holds its file and its password holds the key. Keep only small balances in it.
Created wallet agent-sol (Solana): CEJT6RKEqjgbg7rCpnPZwxNCDie1PmdEWKrRZzqJHyCK
  file    wallets/agent-sol.json
  policy  none (wallets/agent-sol.policy.json would set limits)

Import a private key from a file

key.txt holds 32 bytes of hex.

sauce wallet import treasury key.txt --wallets ./wallets --password-file pw.txt

Imported wallet treasury (EVM): 0x86d5cAFb73644374C84fe0C8f2BBBc97c96Ba64F
  file    wallets/treasury.json
  policy  none (wallets/treasury.policy.json would set limits)

Import a Solana keypair from stdin

keypair.json holds the JSON array of 64 bytes that solana-keygen writes.

sauce wallet import trader-sol - --solana --wallets ./wallets --password-file pw.txt < keypair.json

Imported wallet trader-sol (Solana): 8CZ95CfrKaPCwLPnt23CJqv887ojdtkgvCFf57JxWp9t
  file    wallets/trader-sol.json
  policy  none (wallets/trader-sol.policy.json would set limits)

List the wallets

After wallets/agent.policy.json and wallets/trader-sol.policy.json are written (spending policy):

sauce wallet list --wallets ./wallets

Wallets in ./wallets:
  agent-sol   solana  CEJT6RKEqjgbg7rCpnPZwxNCDie1PmdEWKrRZzqJHyCK
  agent       evm     0xE1Eff146a8463ad592014Bd9cc0D058307364916  (policy)
  trader-sol  solana  8CZ95CfrKaPCwLPnt23CJqv887ojdtkgvCFf57JxWp9t  (policy)
  treasury    evm     0x86d5cAFb73644374C84fe0C8f2BBBc97c96Ba64F

(policy) marks a wallet with a <name>.policy.json beside it.

Print an address

sauce wallet address agent --wallets ./wallets

0xE1Eff146a8463ad592014Bd9cc0D058307364916

Read the refusals

export with no controlling terminal, as in a script, exits 1. A program that runs it in a pseudo-terminal can answer the prompt and read the key, so this does not keep the key from an agent (Agents, wallets and keys):

sauce wallet export agent --wallets ./wallets --password-file pw.txt

sauce wallet export: export shows a key only at a terminal, to the person there: run it in a terminal of your own

A password file that others can read exits 1:

sauce wallet new: --password-file pw-open.txt can be read or written by others (mode 644): a password file must be yours alone. Run `chmod 600 pw-open.txt`, then try again

A key given as the operand exits 2:

sauce wallet import: import reads the key from a file, or from stdin (-): a key on the command line lands in shell history and the process list

Next steps

Wallets, passwords and spending policy: the file format, password sources, other signers and <name>.policy.json.
sauce run: sign and send a program with --wallet.
sauce tx and sauce send: sign with a key that never reaches this machine.
MCP wallets: the same wallets, signing for an agent over stdio.

Start here

Integration guides

Language reference

SauceScript libraries

Runtime and security

Troubleshooting and production

Chains and protocols

@eco-incorp/sauce

@eco-incorp/sauce-compiler

sauce wallet

Synopsis

Description

Options

sauce wallet

sauce wallet new

sauce wallet list

sauce wallet address

sauce wallet import

sauce wallet export

Output

Examples

Create an EVM wallet

Create a Solana wallet with the password from the environment

Import a private key from a file

Import a Solana keypair from stdin

List the wallets

Print an address

Read the refusals

Next steps

​Synopsis

​Description

​Options

​sauce wallet

​sauce wallet new

​sauce wallet list

​sauce wallet address

​sauce wallet import

​sauce wallet export

​Output

​Examples

​Create an EVM wallet

​Create a Solana wallet with the password from the environment

​Import a private key from a file

​Import a Solana keypair from stdin

​List the wallets

​Print an address

​Read the refusals

​Next steps

Synopsis

Description

Options

sauce wallet

sauce wallet new

sauce wallet list

sauce wallet address

sauce wallet import

sauce wallet export

Output

Examples

Create an EVM wallet

Create a Solana wallet with the password from the environment

Import a private key from a file

Import a Solana keypair from stdin

List the wallets

Print an address

Read the refusals

Next steps