> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# sauce wallet

> Keep a signing key on this machine for --wallet, for a developer or an agent that sends cooks from the command line.

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

## Synopsis

```bash theme={null}
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](https://docs.eco.com/sauce-sdk/mcp/wallets.md)).

| 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](https://docs.eco.com/sauce-sdk/cli/wallets-and-policy.md) 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](https://docs.eco.com/sauce-sdk/cli/wallets-and-policy.md)). `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](https://docs.eco.com/sauce/security-considerations.md#agents-wallets-and-keys) covers what an agent running as you can do with them.

## Options

### sauce wallet

| 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:

```json theme={null}
{
  "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

```bash theme={null}
sauce wallet new agent --wallets ./wallets --password-file pw.txt
```

```text theme={null}
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

```bash theme={null}
sauce wallet new agent-sol --solana --wallets ./wallets --password-env SAUCE_WALLET_PASSWORD
```

```text theme={null}
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.

```bash theme={null}
sauce wallet import treasury key.txt --wallets ./wallets --password-file pw.txt
```

```text theme={null}
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.

```bash theme={null}
sauce wallet import trader-sol - --solana --wallets ./wallets --password-file pw.txt < keypair.json
```

```text theme={null}
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](https://docs.eco.com/sauce-sdk/cli/wallets-and-policy.md)):

```bash theme={null}
sauce wallet list --wallets ./wallets
```

```text theme={null}
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

```bash theme={null}
sauce wallet address agent --wallets ./wallets
```

```text theme={null}
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](https://docs.eco.com/sauce/security-considerations.md#agents-wallets-and-keys)):

```bash theme={null}
sauce wallet export agent --wallets ./wallets --password-file pw.txt
```

```text theme={null}
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`:

```text theme={null}
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`:

```text theme={null}
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](https://docs.eco.com/sauce-sdk/cli/wallets-and-policy.md): the file format, password sources, other signers and `<name>.policy.json`.
* [`sauce run`](https://docs.eco.com/sauce-sdk/cli/run): sign and send a program with `--wallet`.
* [`sauce tx`](https://docs.eco.com/sauce-sdk/cli/tx) and [`sauce send`](https://docs.eco.com/sauce-sdk/cli/send): sign with a key that never reaches this machine.
* [MCP wallets](https://docs.eco.com/sauce-sdk/mcp/wallets.md): the same wallets, signing for an agent over stdio.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.