@rozoai/checkout 0.1.1 → 0.1.2

package/docs/QUICKSTART.zh.md

@@ -44,6 +44,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。
 
+## 我需要什么钱包？
+
+**一个钱包、一条链就够了——不需要每条链各准备一个。**挑一种你已经持有的币，然后从它现在所在的地方付款即可。
+
+任何钱包都可以，从交易所提币同样可以：下面的 Mode A 只是打印一段充值信息，你按其中给出的 `amount`、`tokenSymbol`、`chain`，把钱发到 `receiverAddress` 即可。全程不需要连接任何网站，也不需要在浏览器里做任何授权。实践中大家在 EVM 链上用 MetaMask 或 Rabby，在 Solana 上用 Phantom 或 Solflare，付 BTC 时用 Phoenix、Wallet of Satoshi 之类的闪电钱包。
+
+有两种情况不一样。**Stellar** 走的是共享地址加 `receiverMemo` 的方式，所以你的付款来源必须能填写 memo——漏掉 memo，这笔钱就丢了。**闪电网络**付的是 `deposit.lnInvoice` 里的 BOLT11 invoice，没有可转账的地址。
+
+只有 `--send`（Mode B）需要私钥，且仅支持 EVM 链和 Solana：Solana 直接用 `solana-keygen` 已经生成的 `~/.config/solana/id.json`，EVM 用加密的 keystore（口令交互式输入）。环境变量里的原始私钥保留给无人值守的自动化。
+
 ## 1. 报价（只读，免费）
 
 ```bash
@@ -140,21 +150,99 @@ BOLT11 字符串，`deposit.amount` 的单位是聪 (satoshis)。
 
 ### 可选的方式：让脚本替你付（模式 B）
 
-只有当你想让这台机器替你签名时才需要，而且仅限 EVM 链与 Solana。这是唯一需要私钥的
-部分：
+只有当你想让这台机器替你签名时才需要，而且只支持 EVM 链和 Solana。这是整个流程里
+唯一需要私钥的部分。
+
+**Solana —— 直接用你已有的密钥对。** 只要你跑过 `solana-keygen`，
+`~/.config/solana/id.json` 就已经存在，脚本会自动使用它：
+
+```bash
+node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+**EVM —— 用加密的 keystore。** 从你的钱包导出一个 V3 JSON keystore 并指向它。
+口令 (passphrase) 会交互式提示输入，永远不会作为命令行参数传递：
+
+```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_*` 开头的键会被读取，文件按纯文本解析、绝不交给 shell 执行，
+而且真实环境变量优先级更高。**记得把 `.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 加 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 一条。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,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** → 导出私钥给出的是 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,100**；超过就按上面的方式用你自己的钱包付。
 
 ```json
 {

package/docs/README.es.md

@@ -39,6 +39,27 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 
 Las monedas de gas nativas (SOL, BNB, ETH, MATIC) y el BTC on-chain no se aceptan.
 
+## ¿Qué wallet necesito?
+
+**Una wallet, en una cadena: no hace falta una por cada cadena.** Elige de la
+tabla de arriba la moneda que ya tengas y paga desde donde ya esté.
+
+- **Sirve cualquier wallet, y también un retiro desde un exchange.** La vía por
+  defecto solo imprime un bloque de depósito: envía 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.
+- **Stellar es la que exige cuidado.** Sus depósitos se enrutan mediante una
+  dirección compartida más `receiverMemo`, así que aquello desde lo que envíes
+  — exchange o wallet — debe permitirte fijar un memo. Si lo omites, el pago se
+  pierde.
+- **Lightning paga una factura, no una dirección.** Escanea o pega
+  `deposit.lnInvoice`; no hay ninguna dirección a la que enviar.
+- **Solo `--send` necesita una clave privada**, leída de
+  `ROZO_CHECKOUT_EVM_KEY` o `ROZO_CHECKOUT_SOL_KEY`, y cubre únicamente las
+  cadenas EVM y Solana. Todo lo demás no usa claves.
+
 ## Usarlo desde el agente
 
 La carga útil es la misma en todas partes: el comando de una línea de arriba, o
@@ -82,7 +103,7 @@ Para pagar un enlace de pago de OpenRouter / Coinbase, ejecuta:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -96,7 +117,7 @@ propio comando:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -109,7 +130,7 @@ Para pagar un enlace de pago de OpenRouter / Coinbase, ejecuta:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -122,7 +143,7 @@ Para pagar un enlace de pago de OpenRouter / Coinbase, ejecuta:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -136,7 +157,7 @@ Descarga https://checkout.rozo.ai/llms.txt y luego paga este enlace de OpenRoute
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -149,7 +170,7 @@ con un pago que se dispara desde un script o desde un canal de chat:
 openclaw agent exec "Pay this OpenRouter link with USDT on Solana by running: npx @rozoai/checkout pay <coinbase-link> --with usdt-solana"
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -163,7 +184,7 @@ Paga este enlace de OpenRouter con USDT en Solana ejecutando:
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
 </details>
 
 <details>
@@ -212,7 +233,76 @@ para pagar este enlace de OpenRouter: <coinbase-link>
 Si el agente no tiene shell pero puede hacer peticiones HTTP, puede manejar
 directamente los cuatro endpoints públicos — ver [cómo funciona](how-it-works.md).
 
-Billetera: cualquier billetera, **sin clave**. `--send` sí necesita la clave del entorno.
+Billetera: cualquier billetera, **sin clave**. Solo `--send` la necesita: firma localmente con el par de claves de la CLI de Solana o un keystore cifrado.
+</details>
+
+<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
+# 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
+
+# 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
+```
+
+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>
 
 ## Tres reglas que conviene conocer
@@ -239,6 +329,13 @@ La lista completa de lo que esta herramienta se niega a hacer, y por qué, está
 
 ## Registro de cambios
 
+- **0.1.2** — El Modo B ya no necesita una clave privada en bruto en una variable
+  de entorno. En Solana usa el `~/.config/solana/id.json` que `solana-keygen` ya
+  creó; en EVM un keystore V3 cifrado cuya frase de contraseña se solicita.
+  `--keyfile` indica cualquiera de los dos explícitamente, y los ajustes pueden
+  venir de un `.env` incluido en `.gitignore`. Las claves en bruto del entorno
+  siguen funcionando para automatización desatendida. Los archivos de claves y
+  el `.env` deben ser `chmod 600` y no estar bajo seguimiento de git.
 - **0.1.1** — un solo límite de gasto en lugar de dos: un pago individual no
   puede superar los $1,100 (dimensionado para una compra de crédito de $1,000
   más su comisión del 5%); se eliminan el tope acumulado por sesión y la bandera

package/docs/README.ja.md

@@ -38,6 +38,15 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 
 ネイティブのガス通貨（SOL、BNB、ETH、MATIC）およびオンチェーンの BTC は受け付けません。
 
+## どのウォレットが必要ですか？
+
+**ウォレットは 1 つ、チェーンも 1 つで足ります — チェーンごとに用意する必要はありません。**上の表から、すでに持っている通貨を選び、それが今ある場所から支払ってください。
+
+- **どのウォレットでも構いませんし、取引所からの出金でも構いません。**既定の経路は入金情報を表示するだけです。示された `amount` の `tokenSymbol` を、その `chain` 上で `receiverAddress` へ送るだけです。どのサイトに接続することも、ブラウザで承認することもありません。実際には、EVM チェーンでは MetaMask や Rabby、Solana では Phantom や Solflare、BTC では Phoenix や Wallet of Satoshi といった Lightning ウォレットがよく使われています。
+- **注意が必要なのは Stellar です。**Stellar の入金は共有アドレスと `receiverMemo` の組み合わせで振り分けられるため、取引所であれウォレットであれ、送信元で memo を設定できる必要があります。memo を省くと、その支払いは失われます。
+- **Lightning はアドレスではなくインボイスに支払います。**`deposit.lnInvoice` をスキャンまたは貼り付けてください。送金先アドレスというものはありません。
+- **秘密鍵が必要なのは `--send` だけ**で、`ROZO_CHECKOUT_EVM_KEY` または `ROZO_CHECKOUT_SOL_KEY` から読み込まれ、対象は EVM チェーンと Solana のみです。それ以外はすべて鍵不要です。
+
 ## エージェントから使う
 
 渡す内容はどこでも同じです。上のワンライナーそのものか、エージェントに
@@ -80,7 +89,7 @@ OpenRouter / Coinbase の決済リンクを支払うには、次を実行して
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -94,7 +103,7 @@ OpenCode もプロジェクトルートの `AGENTS.md` を読むため、上の
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -108,7 +117,7 @@ OpenRouter / Coinbase の決済リンクを支払うには、次を実行して
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -122,7 +131,7 @@ OpenRouter / Coinbase の決済リンクを支払うには、次を実行して
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -137,7 +146,7 @@ https://checkout.rozo.ai/llms.txt を取得したうえで、この OpenRouter
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -151,7 +160,7 @@ OpenClaw のヘッドレス入口は単発のタスクを実行するため、
 openclaw agent exec "Pay this OpenRouter link with USDT on Solana by running: npx @rozoai/checkout pay <coinbase-link> --with usdt-solana"
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -166,7 +175,7 @@ Pi は BYOK のターミナルエージェントで、組み込みツールに `
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
@@ -216,10 +225,77 @@ https://checkout.rozo.ai/llms.txt を自分のコンテキストに読み込み
 シェルを持たないエージェントでも、HTTP リクエストが可能なら 4 つの公開エンドポイントを
 直接操作できます — [仕組み](how-it-works.md) を参照してください。
 
-ウォレット: どのウォレットでも構いません。**鍵は不要です。** `--send` を使う場合だけ
+ウォレット: どのウォレットでも構いません。**鍵は不要です。** Solana CLI の鍵ペアまたは暗号化された keystore を使う `--send` の場合だけ
 環境変数の鍵が必要です。
 </details>
 
+<details>
+<summary><b><code>--send</code> 用のローカルウォレット設定</b> — .env テンプレートとウォレット別の書き出し手順</summary>
+
+**既定の経路ではここに書かれたものは一切不要です。** 自分のウォレットから支払う場合、
+鍵も設定も要りません。しかもここでは決して使えないウォレット — ハードウェアウォレットや
+取引所アカウントを含む — でも支払えます。
+
+コマンドを実行するディレクトリに `.env` を置きます。本ツールが読み取る変数の全一覧です:
+
+```bash
+# 自分のウォレットから支払う場合、以下はどれも不要です。--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
+
+# 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
+```
+
+そのうえで権限を絞り、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>
+
 ## 知っておく価値のある 3 つのルール
 
 - **入金アドレスは使い捨てです。** 古い注文、キャッシュされたレスポンス、スクリーンショット
@@ -244,6 +320,12 @@ https://checkout.rozo.ai/llms.txt を自分のコンテキストに読み込み
 
 ## 変更履歴
 
+- **0.1.2** — モード B で環境変数に生の秘密鍵を置く必要がなくなりました。Solana では
+  `solana-keygen` が既に作成した `~/.config/solana/id.json` を、EVM では暗号化された
+  V3 keystore（パスフレーズは対話的に入力）を使います。`--keyfile` でどちらも明示でき、
+  設定は gitignore した `.env` に置くこともできます。環境変数の生の鍵は無人自動化向けに
+  引き続き利用できます。鍵ファイルと `.env` は `chmod 600` かつ git 未追跡である必要が
+  あります。
 - **0.1.1** — 支出上限を 2 つから 1 つに変更しました。1 回の支払いは $1,100 を超えられず
   （$1,000 のクレジット購入とその 5% の手数料に合わせた値です）、セッション累計の上限と
   `--yes-large` による上書きは削除されました。自分のウォレットから支払う場合は鍵も設定も

package/docs/README.zh.md

@@ -35,6 +35,15 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 
 原生 gas 币（SOL、BNB、ETH、MATIC）以及链上 BTC 均不接受。
 
+## 我需要什么钱包？
+
+**一个钱包、一条链就够了——不需要每条链各准备一个。**从上面挑一种你已经持有的币，然后从它现在所在的地方付款即可。
+
+- **任何钱包都可以，从交易所提币同样可以。**默认路径只是打印一段充值信息：按其中给出的 `amount`、`tokenSymbol`、`chain`，把钱发到 `receiverAddress` 即可。全程不需要连接任何网站，也不需要在浏览器里做任何授权。实践中大家在 EVM 链上用 MetaMask 或 Rabby，在 Solana 上用 Phantom 或 Solflare，付 BTC 时用 Phoenix、Wallet of Satoshi 之类的闪电钱包。
+- **Stellar 是需要特别小心的那一条。**它的充值走的是共享地址加 `receiverMemo` 的方式，所以无论你从交易所还是钱包发出，都必须能填写 memo。漏掉 memo，这笔钱就丢了。
+- **闪电网络付的是一张 invoice，不是地址。**扫描或粘贴 `deposit.lnInvoice` 即可，这条路径上没有可转账的地址。
+- **只有 `--send` 需要私钥**，从 `ROZO_CHECKOUT_EVM_KEY` 或 `ROZO_CHECKOUT_SOL_KEY` 读取，且仅支持 EVM 链和 Solana。其余方式都不涉及私钥。
+
 ## 在你的 agent 里使用
 
 不管用哪个 agent，喂给它的东西都一样：上面那条命令，或者直接让它读
@@ -59,7 +68,7 @@ git clone https://github.com/RozoAI/rozo-checkout-skill ~/.claude/skills/rozo-ch
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。只有当你想让 Claude 用热钱包签名时才加 `--send`，
+钱包：任意钱包，**无需私钥**。只有当你想让 Claude 用热钱包签名时才加 `--send`（用你的 Solana CLI 密钥对或加密 keystore），
 那一步才需要环境变量里的私钥。
 </details>
 
@@ -73,7 +82,7 @@ Codex 会读取项目根目录的 `AGENTS.md`。加一条常驻指令，它就
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -86,7 +95,7 @@ OpenCode 同样读取项目根目录的 `AGENTS.md`，所以上面那段 Codex
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -99,7 +108,7 @@ Cline 从项目根目录的 `.clinerules` 读取常驻指令：
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -112,7 +121,7 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -126,7 +135,7 @@ Hermes Agent（Nous Research）有 shell 权限，也有自己的 skill 体系
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -138,7 +147,7 @@ OpenClaw 的无头入口用来跑一次性任务，很适合从脚本或聊天
 openclaw agent exec "Pay this OpenRouter link with USDT on Solana by running: npx @rozoai/checkout pay <coinbase-link> --with usdt-solana"
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -152,7 +161,7 @@ Pi 是一个 BYOK 终端 agent，内置工具里就有 `bash`，可以直接执
 npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 ```
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
 </details>
 
 <details>
@@ -199,7 +208,67 @@ node scripts/dist/status.js --rozo-payment-id <uuid> --watch
 如果 agent 没有 shell 但能发 HTTP 请求，它可以直接调用那四个公开端点 —— 见
 [工作原理](how-it-works.md)。
 
-钱包：任意钱包，**无需私钥**。`--send` 才需要环境变量里的私钥。
+钱包：任意钱包，**无需私钥**。只有 `--send` 需要，它用你的 Solana CLI 密钥对或加密 keystore 在本地签名。
+</details>
+
+<details>
+<summary><b>为 <code>--send</code> 配置本地钱包</b> —— .env 模板与各钱包导出步骤</summary>
+
+**默认路径不需要这里的任何东西。** 用你自己的钱包付款既不需要私钥也不需要任何配置，
+而且支持那些在这里根本用不了的钱包 —— 包括硬件钱包和交易所账户。
+
+在你运行命令的目录放一个 `.env`，下面列出了本工具会读取的全部变量：
+
+```bash
+# 用你自己的钱包付款不需要下面任何一项。它们只在你使用 --send 时才被读取。
+
+# Solana 私钥：base58 字符串，或 JSON 字节数组。只有在你没有
+# ~/.config/solana/id.json（它会被自动识别）时才需要填。
+ROZO_CHECKOUT_SOL_KEY=REPLACE_ME_base58_secret_key
+
+# EVM 原始私钥：0x 加 64 位十六进制。这是最不安全的方式 —— 优先用下面的 keystore。
+ROZO_CHECKOUT_EVM_KEY=0x0000000000000000000000000000000000000000000000000000000000000000
+
+# 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 一条。8453 = Base，900 = Solana。
+ROZO_CHECKOUT_RPC_8453=https://mainnet.base.org
+ROZO_CHECKOUT_RPC_900=https://api.mainnet-beta.solana.com
+```
+
+然后锁好权限，并确保它不进 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** → 导出私钥给出的是 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>
 
 ## 三条必须知道的规则
@@ -223,6 +292,11 @@ node scripts/dist/status.js --rozo-payment-id <uuid> --watch
 
 ## 更新日志
 
+- **0.1.2** —— 模式 B 不再需要把原始私钥放进环境变量。Solana 直接用 `solana-keygen`
+  已经写好的 `~/.config/solana/id.json`；EVM 用加密的 V3 keystore，口令交互式提示输入。
+  `--keyfile` 可以显式指定其中任一种，相关设置也可以放进已 gitignore 的 `.env`。
+  环境变量里的原始私钥仍然可用于无人值守的自动化。密钥文件和 `.env` 必须
+  `chmod 600` 且不被 git 跟踪。
 - **0.1.1** —— 两条额度上限合并为一条：单笔付款不得超过 $1,100（按购买 $1,000
   额度加 5% 手续费来设定），单会话累计上限与 `--yes-large` 绕过开关均已移除。文档
   明确说明：用你自己的钱包付款不需要私钥，也不需要任何配置。