@rozoai/checkout 0.1.1 → 0.1.3

package/README.md

@@ -32,18 +32,108 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 | Polygon | `usdt-polygon` `usdc-polygon` | `137` | 6 decimals |
 | Base | `usdc-base` | `8453` | 6 decimals |
 | Solana | `usdt-solana` `usdc-solana` | `900` | SPL; native SOL not supported |
-| Stellar | `usdc-stellar` | `1500` | memo required — shown in the deposit block |
+| Stellar | `usdc-stellar` | `1500` | `MEMO_TEXT` memo required — shown in the deposit block |
 | Bitcoin Lightning | `btc-lightning` | `lightning` | BOLT11; amounts in satoshis |
 
 Native gas coins (SOL, BNB, ETH, MATIC) and on-chain BTC are not accepted.
 
+## Which wallet do I need?
+
+**One wallet, on one chain — not one per chain.** Pick whichever coin above you
+already hold and pay from wherever it already lives.
+
+- **Any wallet works, and so does an exchange withdrawal.** The default path
+  just prints a deposit block: send exactly that `amount` of that
+  `tokenSymbol`, on that `chain`, to that `receiverAddress`. Nothing connects to
+  a site and nothing is approved in a browser. In practice people use MetaMask
+  or Rabby on the EVM chains, Phantom or Solflare on Solana, and a Lightning
+  wallet such as Phoenix or Wallet of Satoshi for BTC.
+- **Stellar is the one to be careful with.** Its deposits route through a shared
+  address plus `receiverMemo`, so whatever you send from — exchange or wallet —
+  must let you set a memo. Omit it and the payment is lost.
+- **Lightning pays an invoice, not an address.** Scan or paste
+  `deposit.lnInvoice`; there is no address to send to.
+- **Only `--send` needs a private key**, read from `ROZO_CHECKOUT_EVM_KEY` or
+  `ROZO_CHECKOUT_SOL_KEY`, and it covers EVM chains and Solana only. Everything
+  else is keyless.
+
 ## Use it from your agent
 
 The payload is the same everywhere: the one-liner above, or point the agent at
 [llms.txt](llms.txt). Agents and scripts should always pass `--with` — the
 picker only appears on a terminal, and there is deliberately no default coin. **Paying from your own wallet never needs a key.** Only
-the optional `--send` flag signs locally, and only that flag reads
-`ROZO_CHECKOUT_EVM_KEY` / `ROZO_CHECKOUT_SOL_KEY`.
+the optional `--send` flag signs locally: on Solana it uses the
+`~/.config/solana/id.json` that `solana-keygen` already created, and on EVM an
+encrypted JSON keystore whose passphrase is prompted. A raw key in the
+environment (or a gitignored `.env`) still works for unattended automation.
+
+<details>
+<summary><b>Set up a local wallet for <code>--send</code></b> — .env template and per-wallet export steps</summary>
+
+**None of this is needed for the default path.** Paying from your own wallet
+needs no key and no configuration, and works with wallets that can never be
+used here — including hardware wallets and exchange accounts.
+
+A `.env` in the directory you run from, with every variable this tool reads:
+
+```bash
+# None of this is needed to pay from your own wallet. These are read only
+# when you use --send.
+
+# Solana secret key: a base58 string, or a JSON byte array. Only needed if you
+# do NOT have ~/.config/solana/id.json, which is picked up automatically.
+ROZO_CHECKOUT_SOL_KEY=REPLACE_ME_base58_secret_key
+
+# EVM raw private key: 64 hex characters, 0x prefix optional. The least safe
+# option — prefer the keystore below.
+ROZO_CHECKOUT_EVM_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
+
+# EVM encrypted V3 keystore: path to the file. Preferred over the raw key.
+ROZO_CHECKOUT_EVM_KEYSTORE=/replace/me/keystores/my-hot-wallet
+
+# Passphrase for that keystore. Only for unattended runs; on a terminal you
+# are prompted instead, and nothing is stored.
+ROZO_CHECKOUT_KEYSTORE_PASSPHRASE=REPLACE_ME_not_a_real_passphrase
+
+# Optional RPC overrides, one per chain id. 8453 = Base, 900 = Solana.
+ROZO_CHECKOUT_RPC_8453=https://mainnet.base.org
+ROZO_CHECKOUT_RPC_900=https://api.mainnet-beta.solana.com
+```
+
+Then lock it down and keep it out of git:
+
+```bash
+chmod 600 .env
+echo '.env' >> .gitignore
+```
+
+**Solana**
+
+- `solana-keygen new` writes `~/.config/solana/id.json`. Nothing to configure —
+  it is found automatically. This is the path we recommend.
+- **Phantom** → Settings → Export Private Key gives a **base58** string. Put it
+  in `ROZO_CHECKOUT_SOL_KEY`.
+- **Solflare** exports a base58 string in current versions and a JSON byte
+  array in older ones. Both are accepted as-is.
+
+**EVM**
+
+- **MetaMask** and **Rabby** → Export private key gives 64 hex characters.
+  Paste it into `ROZO_CHECKOUT_EVM_KEY` as-is; the `0x` prefix is optional.
+- **Encrypted keystore (safer).** Browser wallets export raw keys, not
+  keystores. To turn one into an encrypted keystore, use Foundry:
+  `cast wallet import my-hot-wallet --interactive` prompts for the key and
+  writes an encrypted V3 keystore to `~/.foundry/keystores/my-hot-wallet`
+  (`--keystore-dir` changes where). Point `ROZO_CHECKOUT_EVM_KEYSTORE` at that
+  file. `geth account import` also produces a V3 keystore.
+
+**Wallets that cannot be used with `--send`:** hardware wallets (Ledger,
+Trezor), WalletConnect-only mobile wallets, and exchange accounts. None of them
+hand over a signing key, by design. Use the default keyless path instead — it
+works with all of them.
+
+</details>
+
 
 <details>
 <summary><b>Claude Code</b> — install the skill, or paste the one-liner</summary>
@@ -78,7 +168,9 @@ To pay an OpenRouter / Coinbase payment link, run:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -91,7 +183,9 @@ above works unchanged. The shortest path is still the command itself:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -104,7 +198,9 @@ To pay an OpenRouter / Coinbase payment link, run:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -117,7 +213,9 @@ To pay an OpenRouter / Coinbase payment link, run:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -131,7 +229,9 @@ Fetch https://checkout.rozo.ai/llms.txt, then pay this OpenRouter link:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -144,7 +244,9 @@ trigger from a script or a chat channel:
 openclaw agent exec "Pay this OpenRouter link with USDT on Solana by running: npx @rozoai/checkout pay <coinbase-link> --with usdt-solana"
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -158,7 +260,9 @@ Pay this OpenRouter link with USDT on Solana by running:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 <details>
@@ -190,7 +294,7 @@ refused/failed (read `error.code`), `2` usage, `3` submitted but unconfirmed.
 Full walkthrough: [QUICKSTART](docs/QUICKSTART.md).
 
 Wallet: any wallet, no key. For hot-wallet sending see `send-evm.js` /
-`send-sol.js`, which read `ROZO_CHECKOUT_EVM_KEY` / `ROZO_CHECKOUT_SOL_KEY`.
+`send-sol.js`, which use your Solana CLI keypair or an encrypted keystore.
 </details>
 
 <details>
@@ -206,7 +310,9 @@ to pay this OpenRouter link: <coinbase-link>
 If the agent has no shell but can make HTTP requests, it can drive the four
 public endpoints directly — see [how it works](docs/how-it-works.md).
 
-Wallet: any wallet, no key. `--send` needs the env key.
+Wallet: any wallet, no key. `--send` signs locally using your Solana CLI
+keypair or an encrypted keystore, and supports EVM chains and Solana only —
+Stellar and Lightning are Mode A only.
 </details>
 
 ## Three rules worth knowing
@@ -215,6 +321,10 @@ Wallet: any wallet, no key. `--send` needs the env key.
   cached response or a screenshot.
 - **Send the exact amount shown.** It is normally larger than the invoice — it
   includes the bridge and network fees.
+- **Stellar deposits carry a memo, and it is `MEMO_TEXT`** — even when it looks
+  like a number (`65371582` is text, not an id). Sending it as `MEMO_ID`
+  produces a different memo and the payment will not be matched. The deposit
+  block states the type as `receiverMemoType`.
 - **Never pay a funded order twice.** If a payment has already been detected,
   stop and get a human to reconcile it; a second payment to a one-time address
   is not guaranteed to be credited.
@@ -233,6 +343,21 @@ The full list of what this refuses to do, and why, is in
 
 ## Changelog
 
+- **0.1.3** — fixes found by the first real payment. The built bundles no
+  longer crash with `__filename is not defined` on Node 22+ (the esbuild banner
+  now shims `__filename`/`__dirname` as well as `require`, and every bundle is
+  now executed by the test suite). Stellar deposits state their memo type
+  (`MEMO_TEXT`, even when the memo looks numeric). Orders show remaining
+  validity as a duration ("expires in 47m") in the deposit block and in
+  `status`, with the exact command to make a fresh one. Reusing an existing
+  unpaid order, and asking for a coin that differs from it, are both explained
+  instead of reading as errors.
+- **0.1.2** — Mode B no longer needs a raw private key in an environment
+  variable. On Solana it uses the `~/.config/solana/id.json` that
+  `solana-keygen` already wrote; on EVM an encrypted V3 keystore whose
+  passphrase is prompted. `--keyfile` names either explicitly, and settings can
+  come from a gitignored `.env`. Raw env keys still work for unattended
+  automation. Key files and `.env` must be `chmod 600` and untracked by git.
 - **0.1.1** — one spend limit instead of two: a single payment may not exceed
   $1,100 (sized for a $1,000 credit purchase plus its 5% fee), the cumulative
   session cap and the `--yes-large` override are removed. Docs make it explicit

package/docs/QUICKSTART.es.md

@@ -57,6 +57,29 @@ LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
 Ids de cadena: `1` Ethereum · `56` BNB Chain · `137` Polygon · `8453` Base ·
 `900` Solana · `1500` Stellar · `lightning` Bitcoin Lightning.
 
+## ¿Qué wallet necesito?
+
+**Una wallet, en una cadena: no hace falta una por cada cadena.** Elige la
+moneda que ya tengas y paga desde donde ya esté.
+
+Sirve cualquier wallet, y también un retiro desde un exchange: el Mode A de
+abajo solo imprime un bloque de depósito, y envías exactamente ese `amount` de
+ese `tokenSymbol`, en esa `chain`, a esa `receiverAddress`. Nada se conecta a
+ningún sitio ni se aprueba en el navegador. En la práctica la gente usa
+MetaMask o Rabby en las cadenas EVM, Phantom o Solflare en Solana, y una wallet
+Lightning como Phoenix o Wallet of Satoshi para BTC.
+
+Dos casos son distintos. **Stellar** se enruta mediante una dirección
+compartida más `receiverMemo`, así que aquello desde lo que envíes debe
+permitirte fijar un memo: si lo omites, el pago se pierde. **Lightning** paga
+la factura BOLT11 de `deposit.lnInvoice`; no hay ninguna dirección a la que
+enviar.
+
+Solo `--send` (Mode B) necesita una clave, y cubre únicamente las cadenas EVM y
+Solana: en Solana usa el `~/.config/solana/id.json` que `solana-keygen` ya creó,
+y en EVM un keystore cifrado cuya frase de contraseña se solicita. Una clave en
+bruto en el entorno queda para la automatización desatendida.
+
 ## 1. Cotizarlo (solo lectura, gratis)
 
 ```bash
@@ -136,6 +159,7 @@ exigen los scripts de envío.
 ```
 
 Enviar exactamente los campos que entrega este bloque. Para Lightning,
+En Stellar el memo es **`MEMO_TEXT`** aunque parezca numérico: enviarlo como `MEMO_ID` no coincidirá. `deposit.expiresIn` indica cuánto sigue siendo válida la orden.
 `deposit.lnInvoice` contiene la cadena BOLT11 que hay que escanear, y
 `deposit.amount` está en satoshis.
 
@@ -159,22 +183,115 @@ Eso es todo el Modo A. Continuar en el paso 5.
 
 ### La forma opcional: dejar que el script pague (Modo B)
 
-Solo si se quiere que esta máquina firme por uno, y solo en cadenas EVM y Solana.
-Esta es la única parte que necesita una clave privada:
+Solo si se quiere que esta máquina firme, y únicamente en **cadenas EVM y
+Solana**: no hay `--send` para Stellar ni Lightning, que se pagan desde la
+propia billetera. Esta es la única parte que necesita una clave.
+
+**Solana: usar el par de claves que ya se tiene.** Si alguna vez se ejecutó
+`solana-keygen`, `~/.config/solana/id.json` ya existe y se usa automáticamente:
+
+```bash
+node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+**EVM: usar un keystore cifrado.** Exportar un keystore JSON V3 desde la
+billetera y apuntar a él. La frase de contraseña (passphrase) se solicita de
+forma interactiva; nunca se pasa como bandera:
+
+```bash
+ROZO_CHECKOUT_EVM_KEYSTORE=~/wallets/hot.json \
+  node scripts/dist/send-evm.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+Cualquiera de los dos archivos se puede indicar explícitamente con
+`--keyfile <path>`, y `--dry-run` funciona con todas las fuentes: deriva la
+dirección y ejecuta todas las comprobaciones sin firmar nada.
+
+**Para automatización desatendida**, donde nadie puede escribir una frase de
+contraseña, una clave en bruto en el entorno sigue funcionando igual que antes:
+`ROZO_CHECKOUT_SOL_KEY` o `ROZO_CHECKOUT_EVM_KEY`, o bien
+`ROZO_CHECKOUT_KEYSTORE_PASSPHRASE` junto a un keystore. En una máquina que usa
+una persona, es preferible un archivo de claves.
+
+Estos ajustes también pueden vivir en un `.env` en el directorio desde el que se
+ejecuta (o `--env-file <path>`). Solo se leen de él las claves `ROZO_CHECKOUT_*`,
+se analiza como texto plano y nunca se pasa por un shell, y lo que ya esté en el
+entorno real tiene prioridad. **Añadir `.env` al `.gitignore`.**
+
+Un archivo de claves o un `.env` no debe ser legible por otros usuarios
+(`chmod 600`) ni estar bajo seguimiento de git. Ambos casos se rechazan, no se advierten.
+
+<details>
+<summary><b>Configurar una billetera local para <code>--send</code></b> — plantilla .env y pasos de exportación por billetera</summary>
+
+**Nada de esto hace falta para la ruta por defecto.** Pagar desde la propia
+billetera no necesita clave ni configuración, y funciona con billeteras que aquí
+nunca se pueden usar, incluidas las de hardware y las cuentas de exchange.
+
+Un `.env` en el directorio desde el que se ejecuta, con todas las variables que
+esta herramienta lee:
 
 ```bash
-# Previsualizar exactamente lo que se firmaría — no firma nada
-ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
-  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --dry-run
+# Nada de esto hace falta para pagar desde la propia billetera. Solo se lee
+# cuando se usa --send.
+
+# Clave secreta de Solana: una cadena base58 o un arreglo JSON de bytes. Solo
+# hace falta si NO se tiene ~/.config/solana/id.json, que se detecta solo.
+ROZO_CHECKOUT_SOL_KEY=REPLACE_ME_base58_secret_key
+
+# Clave privada EVM en bruto: 0x seguido de 64 caracteres hex. La opción menos
+# segura: es preferible el keystore de abajo.
+ROZO_CHECKOUT_EVM_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
 
-# Enviar de verdad. --send es obligatorio.
-ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
-  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+# Keystore V3 cifrado para EVM: ruta al archivo. Preferible a la clave en bruto.
+ROZO_CHECKOUT_EVM_KEYSTORE=/replace/me/keystores/my-hot-wallet
+
+# Frase de contraseña de ese keystore. Solo para ejecuciones desatendidas; en
+# una terminal se solicita y no se guarda nada.
+ROZO_CHECKOUT_KEYSTORE_PASSPHRASE=REPLACE_ME_not_a_real_passphrase
+
+# Sobrescrituras de RPC opcionales, una por id de cadena. 8453 = Base,
+# 900 = Solana.
+ROZO_CHECKOUT_RPC_8453=https://mainnet.base.org
+ROZO_CHECKOUT_RPC_900=https://api.mainnet-beta.solana.com
 ```
 
-Usar `send-evm.js` con `ROZO_CHECKOUT_EVM_KEY` para Ethereum, BNB Chain,
-Polygon y Base. Un solo pago no puede superar los **$1,100**; por encima de eso,
-pagar desde la propia billetera como se explica arriba.
+Después, restringir permisos y mantenerlo fuera de git:
+
+```bash
+chmod 600 .env
+echo '.env' >> .gitignore
+```
+
+**Solana**
+
+- `solana-keygen new` escribe `~/.config/solana/id.json`. No hay nada que
+  configurar: se encuentra automáticamente. Es la ruta recomendada.
+- **Phantom** → Settings → Export Private Key da una cadena **base58**. Va en
+  `ROZO_CHECKOUT_SOL_KEY`.
+- **Solflare** exporta una cadena base58 en las versiones actuales y un arreglo
+  JSON de bytes en las antiguas. Ambos se aceptan tal cual.
+
+**EVM**
+
+- **MetaMask** y **Rabby** exportan la clave privada como 64 caracteres hex.
+  Pegarla tal cual en `ROZO_CHECKOUT_EVM_KEY`; el prefijo `0x` es opcional.
+- **Keystore cifrado (más seguro).** Las billeteras de navegador exportan claves
+  en bruto, no keystores. Para convertir una en un keystore cifrado, usar
+  Foundry: `cast wallet import my-hot-wallet --interactive` pide la clave y
+  escribe un keystore V3 cifrado en `~/.foundry/keystores/my-hot-wallet`
+  (`--keystore-dir` cambia la ubicación). Apuntar `ROZO_CHECKOUT_EVM_KEYSTORE` a
+  ese archivo. `geth account import` también genera un keystore V3.
+
+**Billeteras que no se pueden usar con `--send`:** billeteras de hardware
+(Ledger, Trezor), billeteras móviles solo con WalletConnect y cuentas de
+exchange. Por diseño, ninguna entrega una clave de firma. Esos casos usan la
+ruta por defecto sin clave, que funciona con todas ellas.
+
+</details>
+
+Un solo pago no puede superar **$1,100**; por encima de eso, pagar desde la
+propia billetera como arriba.
 
 ```json
 {

package/docs/QUICKSTART.ja.md

@@ -54,6 +54,16 @@ LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
 チェーン id: `1` Ethereum · `56` BNB Chain · `137` Polygon · `8453` Base ·
 `900` Solana · `1500` Stellar · `lightning` Bitcoin Lightning。
 
+## どのウォレットが必要ですか？
+
+**ウォレットは 1 つ、チェーンも 1 つで足ります — チェーンごとに用意する必要はありません。**すでに持っている通貨を選び、それが今ある場所から支払ってください。
+
+どのウォレットでも構いませんし、取引所からの出金でも構いません。下記の Mode A は入金情報を表示するだけで、示された `amount` の `tokenSymbol` を、その `chain` 上で `receiverAddress` へ送るだけです。どのサイトに接続することも、ブラウザで承認することもありません。実際には、EVM チェーンでは MetaMask や Rabby、Solana では Phantom や Solflare、BTC では Phoenix や Wallet of Satoshi といった Lightning ウォレットがよく使われています。
+
+異なるケースが 2 つあります。**Stellar** は共有アドレスと `receiverMemo` の組み合わせで振り分けられるため、送信元で memo を設定できる必要があります。memo を省くと、その支払いは失われます。**Lightning** は `deposit.lnInvoice` にある BOLT11 インボイスに支払います。送金先アドレスというものはありません。
+
+鍵が必要なのは `--send`（Mode B）だけで、対象は EVM チェーンと Solana のみです。Solana では `solana-keygen` が既に作成した `~/.config/solana/id.json` を、EVM では暗号化された keystore（パスフレーズは対話的に入力）を使います。環境変数の生の鍵は無人自動化向けに残されています。
+
 ## 1. 見積もりを取得する（読み取り専用、無料）
 
 ```bash
@@ -131,6 +141,7 @@ node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confi
 ```
 
 このブロックが示すフィールドを、そのとおりに送金してください。Lightning の場合、
+Stellar の memo は数字に見えても**常に `MEMO_TEXT`** です — `MEMO_ID` として送ると一致しません。`deposit.expiresIn` に残りの有効時間が出ます。
 `deposit.lnInvoice` にスキャン用の BOLT11 文字列が入り、`deposit.amount` は
 satoshi 単位になります。
 
@@ -153,22 +164,110 @@ satoshi 単位になります。
 
 ### 任意の方法: スクリプトに支払わせる（モード B）
 
-このマシンに署名させたい場合にだけ、そして EVM チェーンと Solana でのみ使えます。
-秘密鍵が必要なのはこの部分だけです:
+このマシンに署名させたい場合のみで、対象は **EVM チェーンと Solana だけ**です。Stellar と
+Lightning に `--send` はなく、自分のウォレットから支払います。鍵が必要なのはこの部分だけです。
+
+**Solana — すでにある鍵ペアをそのまま使います。** `solana-keygen` を一度でも実行して
+いれば `~/.config/solana/id.json` が既に存在し、自動的に使われます:
+
+```bash
+node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+**EVM — 暗号化された keystore を使います。** ウォレットから V3 形式の JSON keystore を
+書き出し、それを指定してください。パスフレーズは対話的に尋ねられ、フラグとして渡す
+ことは決してありません:
+
+```bash
+ROZO_CHECKOUT_EVM_KEYSTORE=~/wallets/hot.json \
+  node scripts/dist/send-evm.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+どちらのファイルも `--keyfile <path>` で明示的に指定できます。`--dry-run` はすべての
+取得元で機能し、アドレスを導出してすべてのチェックを実行しますが、署名は行いません。
+
+**無人自動化の場合**（パスフレーズを入力できる人がいない場合）は、環境変数の生の鍵が
+これまでどおり使えます — `ROZO_CHECKOUT_SOL_KEY` または `ROZO_CHECKOUT_EVM_KEY`、
+あるいは keystore と併せて `ROZO_CHECKOUT_KEYSTORE_PASSPHRASE` です。人が使うマシンでは
+鍵ファイルを優先してください。
+
+これらの設定は、実行するディレクトリの `.env` に置くこともできます（`--env-file <path>`
+でも指定できます）。読み込まれるのは `ROZO_CHECKOUT_*` のキーだけで、ファイルはテキスト
+として解析され、シェルで評価されることは決してありません。実際の環境変数のほうが優先
+されます。**`.env` は `.gitignore` に追加してください。**
+
+鍵ファイルと `.env` は他のユーザーから読めてはならず（`chmod 600`）、git で追跡されて
+いてもいけません。どちらの場合も警告ではなく拒否されます。
+
+<details>
+<summary><b><code>--send</code> 用のローカルウォレット設定</b> — .env テンプレートとウォレット別の書き出し手順</summary>
+
+**既定の経路ではここに書かれたものは一切不要です。** 自分のウォレットから支払う場合、
+鍵も設定も要りません。しかもここでは決して使えないウォレット — ハードウェアウォレットや
+取引所アカウントを含む — でも支払えます。
+
+コマンドを実行するディレクトリに `.env` を置きます。本ツールが読み取る変数の全一覧です:
 
 ```bash
-# 署名される内容を正確にプレビューします — 署名は一切行いません
-ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
-  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --dry-run
+# 自分のウォレットから支払う場合、以下はどれも不要です。--send を使うときだけ
+# 読み込まれます。
+
+# Solana の秘密鍵: base58 文字列、または JSON のバイト配列。
+# ~/.config/solana/id.json (自動的に使われます) が無い場合にのみ必要です。
+ROZO_CHECKOUT_SOL_KEY=REPLACE_ME_base58_secret_key
+
+# EVM の生の秘密鍵: 0x + 16 進 64 文字。最も安全でない選択肢です。
+# 下の keystore を優先してください。
+ROZO_CHECKOUT_EVM_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
 
-# 実際に送金します。--send は必須です。
-ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
-  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+# EVM の暗号化 V3 keystore: そのファイルへのパス。上の生の鍵より推奨されます。
+ROZO_CHECKOUT_EVM_KEYSTORE=/replace/me/keystores/my-hot-wallet
+
+# その keystore のパスフレーズ。無人実行のときだけ必要で、端末では対話的に
+# 尋ねられ、保存もされません。
+ROZO_CHECKOUT_KEYSTORE_PASSPHRASE=REPLACE_ME_not_a_real_passphrase
+
+# 任意の RPC 上書き。チェーン id ごとに 1 行。8453 = Base、900 = Solana。
+ROZO_CHECKOUT_RPC_8453=https://mainnet.base.org
+ROZO_CHECKOUT_RPC_900=https://api.mainnet-beta.solana.com
 ```
 
-Ethereum、BNB Chain、Polygon、Base では `send-evm.js` を `ROZO_CHECKOUT_EVM_KEY` と
-併せて使います。1 回の支払いは **$1,100** を超えられません。それを超える場合は、上記の
-とおり自分のウォレットから支払ってください。
+そのうえで権限を絞り、git に入らないようにします:
+
+```bash
+chmod 600 .env
+echo '.env' >> .gitignore
+```
+
+**Solana**
+
+- `solana-keygen new` は `~/.config/solana/id.json` を書き出します。設定は不要で、
+  自動的に見つかります。これが推奨の経路です。
+- **Phantom** → Settings → Export Private Key で得られるのは **base58** 文字列です。
+  `ROZO_CHECKOUT_SOL_KEY` に設定してください。
+- **Solflare** は現行バージョンでは base58 文字列、古いバージョンでは JSON のバイト配列を
+  書き出します。どちらもそのまま使えます。
+
+**EVM**
+
+- **MetaMask** と **Rabby** の秘密鍵の書き出しは 16 進 64 文字です。そのまま
+  `ROZO_CHECKOUT_EVM_KEY` に貼り付けてください。`0x` 接頭辞は付けても付けなくても
+  構いません。
+- **暗号化 keystore (より安全)。** ブラウザーウォレットが書き出せるのは生の鍵だけで、
+  keystore ではありません。生の鍵を暗号化 keystore に変えるには Foundry を使います:
+  `cast wallet import my-hot-wallet --interactive` が鍵の入力を促し、暗号化された
+  V3 keystore を `~/.foundry/keystores/my-hot-wallet` に書き出します
+  (`--keystore-dir` で場所を変更できます)。`ROZO_CHECKOUT_EVM_KEYSTORE` をその
+  ファイルに向けてください。`geth account import` も V3 keystore を生成します。
+
+**`--send` に使えないウォレット:** ハードウェアウォレット (Ledger、Trezor)、
+WalletConnect 専用のモバイルウォレット、取引所アカウント。いずれも設計上、署名鍵を
+渡しません。これらの場合は既定の鍵なしの経路を使ってください — すべてで動作します。
+
+</details>
+
+1 回の支払いは **$1,100** を超えられません。それ以上は上記のとおり自分のウォレットから
+支払ってください。
 
 ```json
 {