SAW

Documentation

Agents: prefer agents.md or llms.txt — same content, plain text.

Install

Download a binary from the latest release and place saw on PATH. Verify with saw version.

From source:

make build && make install

Agent skill (Cursor / compatible skill hosts):

npx skills add AxLabs/simple-agent-wallet --skill saw -g -y

Init

saw init                              # interactive TTY wizard
saw init create --family evm
saw init create --family solana
saw init import --family evm          # private key or mnemonic on stdin
saw init import --family solana
saw init import --family hedera --account-id 0.0.x
saw init status                       # addresses only; never secrets

Secrets: stdin / prompts only — never CLI flags. Optional encryption via --encrypt / SAW_PASSWORD.

Wallet: ~/.config/saw/wallet.json (mode 0600). Override dir: SAW_CONFIG_DIR.

RPC config

Edit ~/.config/saw/config.env:

SAW_RPC_8453=https://mainnet.base.org
SAW_RPC_84532=https://sepolia.base.org
SAW_SOLANA_RPC=https://api.mainnet-beta.solana.com
SAW_HEDERA_NETWORK=testnet

Pay flow (x402)

Do not curl pay URLs and scrape PAYMENT-REQUIRED headers. Tool output truncates long base64. saw fetches and signs them itself.

  1. Inspect (do not pay yet): 
    saw inspect <url> [--method GET|POST] [--data '...']
  2. Confirm with the user: amount, asset, network, payTo, scheme, and feePayer when present.
  3. If EVM permit2 and allowance may be missing: 
    saw approve-permit2 --chain-id <N> --token 0x… --confirm
  4. Pay once (same method/body as inspect): 
    saw pay <url> --confirm \
  [--scheme exact|batch-settlement] \
  [--network eip155:8453|solana:…|hedera:testnet] \
  [--asset 0x…] \
  [--asset-transfer-method eip3009|permit2] \
  [--method POST --data '...']

--confirm is required. One attempt; no loops without user confirmation.

Batch settlement

Configure SAW_RPC_<chainId> so channel recovery works. Sessions persist under ~/.config/saw/channels/. Optional: SAW_BATCH_DEPOSIT_MULTIPLIER (default 5). 

saw channels
saw refund <url> --confirm
saw refund <url> --amount <units> --confirm

Commands

Command Purpose
saw init / create / import / status Multi-family wallet lifecycle
saw address [--family] Print configured addresses
saw balance … Native / token balances
saw inspect <url> Decode 402 accepts[]
saw pay <url> --confirm Sign and retry
saw channels / saw refund Batch-settlement sessions
saw approve-permit2 … --confirm ERC-20 approve Permit2
saw transfer … --confirm EVM / Solana / Hedera transfers
saw call / saw abi encode EVM only

Rules

  • Never print private keys or mnemonics after init.
  • Never invent header names — use saw inspect / saw pay output.
  • Never pass PAYMENT-REQUIRED / PAYMENT-SIGNATURE tokens as CLI args.
  • Discovery of merchant URLs comes from the user or the 402 body.
  • If the selected accept family has no credentials, run saw init for that family first.