@rozoai/checkout 0.1.1 → 0.1.3

package/docs/README.ja.md

@@ -33,11 +33,20 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 | Polygon | `usdt-polygon` `usdc-polygon` | `137` | 小数点以下 6 桁 |
 | Base | `usdc-base` | `8453` | 小数点以下 6 桁 |
 | Solana | `usdt-solana` `usdc-solana` | `900` | SPL。ネイティブの SOL は非対応 |
-| Stellar | `usdc-stellar` | `1500` | メモが必須 — 入金ブロックに表示されます |
+| Stellar | `usdc-stellar` | `1500` | `MEMO_TEXT` のメモが必須 — 入金ブロックに表示されます |
 | Bitcoin Lightning | `btc-lightning` | `lightning` | BOLT11。金額は satoshi 単位 |
 
 ネイティブのガス通貨（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`（EVM チェーンと Solana のみ、Stellar と Lightning はモード A 専用）の場合だけ
 環境変数の鍵が必要です。
 </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,19 @@ https://checkout.rozo.ai/llms.txt を自分のコンテキストに読み込み
 
 ## 変更履歴
 
+- **0.1.3** — 最初の実際の支払いで見つかった不具合の修正。ビルド済みバンドルが Node 22 以降で
+  `__filename is not defined` により停止しなくなりました（esbuild の banner が `require` に加えて
+  `__filename`/`__dirname` も定義し、テストが各バンドルを実際に実行するようになりました）。Stellar の
+  入金では memo の種類（`MEMO_TEXT`。memo が数字に見える場合も同様）を明示します。注文の残り有効時間を
+  入金ブロックと `status` の両方で継続時間として表示し（"expires in 47m"）、期限切れ時には新しい注文を
+  作るコマンドをそのまま示します。既存の未払い注文の再利用と、それと異なる通貨を指定した場合の双方を、
+  エラーではなく説明として提示します。
+- **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

@@ -30,11 +30,20 @@ npx @rozoai/checkout pay <coinbase-link> --with usdt-solana
 | Polygon | `usdt-polygon` `usdc-polygon` | `137` | 6 位小数 |
 | Base | `usdc-base` | `8453` | 6 位小数 |
 | Solana | `usdt-solana` `usdc-solana` | `900` | SPL；不支持原生 SOL |
-| Stellar | `usdc-stellar` | `1500` | 必须带 memo —— 会在充值信息块里给出 |
+| Stellar | `usdc-stellar` | `1500` | 必须带 `MEMO_TEXT` memo —— 会在充值信息块里给出 |
 | Bitcoin Lightning | `btc-lightning` | `lightning` | BOLT11；金额单位为聪 |
 
 原生 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 在本地签名；仅支持 EVM 链和 Solana —— Stellar 与闪电网络只能用模式 A。
 </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,17 @@ node scripts/dist/status.js --rozo-payment-id <uuid> --watch
 
 ## 更新日志
 
+- **0.1.3** —— 第一笔真实付款暴露出来的问题修复。构建产物在 Node 22+ 上不再因
+  `__filename is not defined` 崩溃（esbuild banner 现在同时注入 `__filename`/`__dirname`
+  和 `require`，并且测试会真正执行每一个构建产物）。Stellar 充值现在会明确标出 memo
+  类型（`MEMO_TEXT`，即使 memo 看起来是纯数字）。订单在充值信息块和 `status` 里都会以
+  时长显示剩余有效期（"expires in 47m"），过期时给出重新下单的完整命令。复用已有的未付
+  订单、以及所选币种与已有订单不一致这两种情况，现在都会被解释清楚，而不是看起来像报错。
+- **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` 绕过开关均已移除。文档
   明确说明：用你自己的钱包付款不需要私钥，也不需要任何配置。

package/docs/safety.md

@@ -58,9 +58,13 @@ reviewing or extending the code.
   never become a second transfer. Transactions are signed before broadcast so
   the hash is known in advance; on an ambiguous result the scripts look that
   exact transaction up instead of rebroadcasting.
-- **Hot-wallet controls.** Keys come from the environment only
-  (`ROZO_CHECKOUT_EVM_KEY`, `ROZO_CHECKOUT_SOL_KEY`), are never printed and
-  never accepted on the command line; library and RPC errors are redacted
+- **Hot-wallet controls.** A signing key is read from a local key file (a
+  solana-keygen keypair, or an encrypted V3 keystore whose passphrase is
+  prompted) or from the environment for unattended runs. A key file that is
+  readable by other users, or tracked by git, is refused — as is a `.env`
+  carrying the same settings, which is parsed as plain text and never
+  evaluated by a shell. Keys and passphrases
+  are never accepted on the command line, and are never printed; library and RPC errors are redacted
   before display, including credential-bearing provider URLs, bearer tokens and
   key-shaped strings. The scripts refuse to run when any `.env`/`.env.*` in the
   working directory is git-tracked, and refuse just as hard when git cannot

package/llms.txt

@@ -25,8 +25,40 @@ usdc-ethereum, usdt-polygon, usdc-polygon, usdc-base, usdc-stellar, btc-lightnin
 
 DEFAULT PATH NEEDS NO KEY: `pay` prints a deposit address for the user to pay from
 any wallet. No private key, no environment variable, no configuration. Only the
-optional --send flag signs locally, and only that flag reads
-ROZO_CHECKOUT_EVM_KEY / ROZO_CHECKOUT_SOL_KEY (from the environment, never argv).
+optional --send flag signs locally. Its key comes from the first source that
+exists: --keyfile <path>; then ~/.config/solana/id.json (the keypair
+solana-keygen already wrote) for Solana or ROZO_CHECKOUT_EVM_KEYSTORE (an
+encrypted V3 keystore, passphrase prompted, never argv) for EVM; then a raw key
+in ROZO_CHECKOUT_SOL_KEY / ROZO_CHECKOUT_EVM_KEY, which is the unattended-
+automation option. Those settings may also come from a .env in the working
+directory (or --env-file <path>): only ROZO_CHECKOUT_* keys are read from it, it
+is parsed as text and never shell-evaluated, and the real environment wins.
+Key files and .env must be chmod 600 and untracked by git.
+
+## Local wallet setup for --send (not needed for the default keyless path)
+
+.env keys (only ROZO_CHECKOUT_* are read; real env wins; chmod 600; gitignore):
+  ROZO_CHECKOUT_SOL_KEY               base58 string OR JSON byte array
+  ROZO_CHECKOUT_EVM_KEY               64 hex chars, 0x prefix optional
+  ROZO_CHECKOUT_EVM_KEYSTORE          path to an encrypted V3 keystore
+  ROZO_CHECKOUT_KEYSTORE_PASSPHRASE   unattended runs only; else prompted
+  ROZO_CHECKOUT_RPC_<chainId>         e.g. ROZO_CHECKOUT_RPC_8453 (Base),
+                                      ROZO_CHECKOUT_RPC_900 (Solana)
+
+Where the material comes from:
+- Solana: `solana-keygen new` -> ~/.config/solana/id.json, found automatically
+  (preferred). Phantom exports base58; Solflare exports base58 (current) or a
+  JSON byte array (older). Both accepted.
+- EVM: MetaMask/Rabby export 64 hex chars with no 0x prefix; paste as-is, the
+  prefix is optional. For an encrypted keystore, Foundry's
+  `cast wallet import <name> --interactive` writes a V3 keystore to
+  ~/.foundry/keystores/<name>; `geth account import` also writes one. Browser
+  wallets do not export keystores, only raw keys.
+- --send supports EVM chains and Solana ONLY. Stellar and Lightning are paid
+  from the user's own wallet (Mode A); there is no local signing for them.
+- Hardware wallets, WalletConnect-only wallets and exchange accounts CANNOT be
+  used with --send. Those users take the default keyless path, which works with
+  any wallet.
 With --send, one limit applies: a single payment may not exceed $1,100, with no
 override; larger invoices go through the keyless path.
 
@@ -46,6 +78,12 @@ chainId "1" Ethereum (USDC, USDT) · "56" BNB Chain (USDC, USDT; 18-decimals) ·
 amounts in integer satoshis via source.amountUnit=="sats").
 Native SOL/ETH/BNB are NOT supported — stablecoins (or Lightning BTC) only.
 
+WALLET: one wallet on one of these chains is enough — not one per chain. Any
+wallet, or an exchange withdrawal, can fund the deposit address; nothing
+connects to a site. Stellar is the exception that must be able to set a memo,
+and Lightning pays a BOLT11 invoice rather than an address. Only --send needs a
+private key (EVM and Solana only); every other path is keyless.
+
 ## Flow (4 HTTP calls, all public)
 
 1) Quote (read-only, safe):
@@ -72,7 +110,11 @@ Native SOL/ETH/BNB are NOT supported — stablecoins (or Lightning BTC) only.
    Pay EXACTLY source.amount of the requested token on the requested chain to
    source.receiverAddress, including every other field the block carries (Stellar
    routes on a shared hub address plus source.receiverMemo, so omitting the memo
-   loses the payment).
+   loses the payment). The Stellar memo is ALWAYS MEMO_TEXT, even when it is all
+   digits (e.g. 65371582) — sending it as MEMO_ID produces a different memo and
+   the payment will not match. The deposit block reports this as
+   receiverMemoType. Orders expire: deposit.expiresIn / status expiry.expiresIn
+   give the remaining validity as a duration.
    For Lightning, pay the BOLT11 in source.lnInvoice (receiverAddress is empty).
 
 4) Poll until settled:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Pay an OpenRouter Coinbase Payment Link with BTC Lightning, or USDT/USDC on Solana, BNB Chain, Ethereum, Polygon, Base or Stellar.",
   "license": "MIT",