@rozoai/checkout 0.1.0 → 0.1.2

package/docs/QUICKSTART.md

@@ -0,0 +1,328 @@
+# Quick start
+
+**English** | [简体中文](QUICKSTART.zh.md) | [日本語](QUICKSTART.ja.md) | [Español](QUICKSTART.es.md)
+
+Pay an OpenRouter Coinbase Payment Link with USDT/USDC on Solana, BNB Chain,
+Ethereum, Polygon, Base or Stellar, or with BTC over Lightning. Five minutes.
+For how it works and why, see [README.md](../README.md).
+
+## The one-liner
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID
+```
+
+That runs every step below for you: pick a coin, quote, create, review,
+confirm, deposit instructions, then polling until settlement. At the coin
+prompt you can paste your wallet address and the picker will check your
+balances and mark which coins you can afford — optional, and it never changes
+what gets signed.
+
+If you already know your coin, name it and skip the question:
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID --with usdt-solana
+```
+
+Coins for `--with`: `usdt-solana`, `usdc-solana`, `usdt-bnb`, `usdc-bnb`,
+`usdt-ethereum`, `usdc-ethereum`, `usdt-polygon`, `usdc-polygon`, `usdc-base`,
+`usdc-stellar`, `btc-lightning`. Scripts and agents must pass `--with`: the
+picker only appears on a terminal, and there is no default coin.
+
+By default it just prints an address for you to pay from any wallet — no key
+and no configuration needed. Add `--send` only if you want the CLI to sign
+from a hot wallet instead, and `--json` for machine-readable output.
+
+The rest of this page is the same flow run one step at a time, which is what
+you want if something goes wrong or you are scripting it yourself.
+
+## Before you start
+
+- **Node 18 or newer** (`node -v`). Nothing else to install — `npx` fetches the
+  CLI, and the cloned `scripts/dist/*.js` are self-contained bundles.
+- **A wallet** holding the coin you want to pay with, on the chain you pick.
+- **The Coinbase link**, e.g.
+  `https://payments.coinbase.com/payment-links/pl_01YOURLINKID`.
+- No account and no API key. Every endpoint here is public.
+
+Set it once:
+
+```bash
+LINK="https://payments.coinbase.com/payment-links/pl_01YOURLINKID"
+```
+
+Chain ids: `1` Ethereum · `56` BNB Chain · `137` Polygon · `8453` Base ·
+`900` Solana · `1500` Stellar · `lightning` Bitcoin Lightning.
+
+## Which wallet do I need?
+
+**One wallet, on one chain — not one per chain.** Pick whichever coin you
+already hold and pay from wherever it already lives.
+
+Any wallet works, and so does an exchange withdrawal: Mode A below just prints
+a deposit block, and you 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.
+
+Two cases differ. **Stellar** routes through a shared address plus
+`receiverMemo`, so whatever you send from must let you set a memo — omit it and
+the payment is lost. **Lightning** pays the BOLT11 invoice in
+`deposit.lnInvoice`; there is no address to send to.
+
+Only `--send` (Mode B) needs a private key, from `ROZO_CHECKOUT_EVM_KEY` or
+`ROZO_CHECKOUT_SOL_KEY`, and it covers EVM chains and Solana only.
+
+## 1. Quote it (read-only, free)
+
+```bash
+node scripts/dist/quote.js --url "$LINK"
+```
+
+```json
+{
+  "success": true,
+  "merchant": "OpenRouter, Inc.",
+  "invoice": { "amount": "1050.00", "fiat": { "amount": "1050.00", "currency": "USD" } },
+  "callerPays": "1050.00",
+  "coinbaseExpiryIso": "2026-08-09T10:00:00.000Z"
+}
+```
+
+`"success": false` with `LINK_NO_LONGER_PAYABLE` means the link is used or
+expired — ask for a fresh one and stop.
+
+## 2. Create the order
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+```
+
+No money moves, and an unfunded order simply expires. The full deposit address
+is **withheld** at this stage — you get a masked summary to check first.
+
+```json
+{
+  "success": true,
+  "rozoPaymentId": "11111111-2222-4333-8444-555555555555",
+  "invoice": { "amount": "1050.000000", "currency": "USD" },
+  "deposit": null,
+  "depositWithheld": true,
+  "display": {
+    "chain": "Solana",
+    "amount": "1054.410000 USDT",
+    "payToMasked": "9WzDXw...AWWM"
+  },
+  "expiry": { "effectiveDeadlineIso": "2026-08-08T11:00:00.000Z", "minutesOfSlack": 55 }
+}
+```
+
+This example is the flagship case: a **$1,050.00** invoice for $1,000 of
+OpenRouter credits. Any invoice up to **$1,100** can be paid this way.
+
+**Check `display.amount` before going on.** It is normally larger than the
+invoice — it includes the bridge and network fees. Note the `rozoPaymentId`;
+every later command uses it.
+
+## 3. Confirm
+
+Only once you have decided to pay, re-run the same command with `--confirm`:
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+```
+
+This releases the full deposit details and records the confirmation the send
+scripts require.
+
+```json
+{
+  "success": true,
+  "confirmed": true,
+  "deposit": {
+    "chain": "Solana",
+    "tokenSymbol": "USDT",
+    "receiverAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+    "receiverMemo": "rozo-901",
+    "amount": "1054.410000",
+    "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+  }
+}
+```
+
+Send exactly the fields this block gives you. For Lightning,
+`deposit.lnInvoice` holds the BOLT11 string to scan, and `deposit.amount` is
+in satoshis.
+
+## 4. Pay
+
+### The simple way: from your own wallet
+
+**No key, no environment variable, no configuration.** Open any wallet, and
+send exactly what the `deposit` block above says:
+
+- the `amount` of the `tokenSymbol`,
+- on the `chain`,
+- to the `receiverAddress` — copied from the JSON, never retyped.
+
+If the block contains any other field, such as `receiverMemo`, include it
+exactly as given; it is part of the address for that chain. For Lightning,
+scan or paste `deposit.lnInvoice` instead.
+
+That is the whole of Mode A. Skip to step 5.
+
+### The optional way: let the script pay (Mode B)
+
+Only if you want this machine to sign for you, and only on EVM chains and
+Solana. This is the only part that needs a key.
+
+**Solana — use the keypair you already have.** If you have ever run
+`solana-keygen`, `~/.config/solana/id.json` already exists and is used
+automatically:
+
+```bash
+node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+**EVM — use an encrypted keystore.** Export a V3 JSON keystore from your
+wallet and point at it. The passphrase is prompted; it is never a flag:
+
+```bash
+ROZO_CHECKOUT_EVM_KEYSTORE=~/wallets/hot.json \
+  node scripts/dist/send-evm.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+Either file can also be given explicitly with `--keyfile <path>`, and
+`--dry-run` works with every source: it derives the address and runs all the
+checks without signing anything.
+
+**For unattended automation**, where nobody can type a passphrase, a raw key in
+the environment still works exactly as before — `ROZO_CHECKOUT_SOL_KEY` or
+`ROZO_CHECKOUT_EVM_KEY`, or `ROZO_CHECKOUT_KEYSTORE_PASSPHRASE` alongside a
+keystore. On a machine a person uses, prefer a key file.
+
+These settings can also live in a `.env` in the directory you run from (or
+`--env-file <path>`). Only `ROZO_CHECKOUT_*` keys are read from it, it is
+parsed as plain text and never run through a shell, and anything already in
+your real environment wins. **Add `.env` to your `.gitignore`.**
+
+A key file or `.env` must not be readable by other users (`chmod 600`) and must
+not be tracked by git. Both are refused rather than warned about.
+
+<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>
+
+
+A single payment may not exceed **$1,100**; above that, pay from your own
+wallet as above.
+
+```json
+{
+  "success": true,
+  "submitted": true,
+  "confirmed": true,
+  "txHash": "3Bxs4h24hBjHziQ8UJqSjqjbjWQq2sQ3yV9Fq4HrVh5c"
+}
+```
+
+## 5. Watch it settle
+
+```bash
+node scripts/dist/status.js --rozo-payment-id <rozoPaymentId> --watch --timeout 600
+```
+
+```json
+{
+  "success": true,
+  "state": "settled",
+  "terminal": true,
+  "payin": { "txHash": "3Bxs4h24...", "confirmedAt": "2026-08-08T10:05:00.000Z" }
+}
+```
+
+States run `awaiting_deposit` → `payin_detected` → `payin_confirmed` →
+`bridging` → `paying_coinbase` → `settled`. Your on-chain transaction
+confirming is not the end: keep polling until `settled`.
+
+## If something goes wrong
+
+Read `error.code`. The three you are most likely to hit:
+
+| `error.code` | What happened | What to do |
+|---|---|---|
+| `LINK_NO_LONGER_PAYABLE` | someone already paid the link, or it expired | ask the merchant for a fresh link; do not pay anything |
+| `EXPIRY_MARGIN` | too little time left to fund, bridge and settle safely | let the order expire, then start again from step 1 |
+| `ALREADY_SENT` | a send is already recorded for this order | do **not** send again; run `status.js` and check the chain first |
+
+**If any money has already left your wallet, never pay again.** Keep the
+`linkId`, the `rozoPaymentId` and every transaction hash, and get a human to
+reconcile it. A second payment to a one-time deposit address is not guaranteed
+to be credited.
+
+The full error table is in [README.md](../README.md), and the agent-facing
+instructions are in [SKILL.md](../SKILL.md).

package/docs/QUICKSTART.zh.md

@@ -0,0 +1,289 @@
+# 快速开始
+
+[English](QUICKSTART.md) | **简体中文** | [日本語](QUICKSTART.ja.md) | [Español](QUICKSTART.es.md)
+
+用 Solana、BNB Chain、Ethereum、Polygon、Base 或 Stellar 上的 USDT/USDC，或者用走
+Lightning 的 BTC，去支付一个 OpenRouter Coinbase 收款链接 (Payment Link)。五分钟搞定。
+工作原理与设计理由见 [README.md](../README.md)。
+
+## 一行命令搞定
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID
+```
+
+这一条命令会替你跑完下面的每一步：选币、报价、创建订单、核对、确认、充值指令，然后一直轮询到结清。在选币那一步，你可以粘贴自己的钱包地址，它会去查余额并标出哪些币你付得起 —— 这是可选的，而且不会改变任何实际签名的内容。
+
+如果你已经知道要用哪种币，直接指定就能跳过这一问：
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID --with usdt-solana
+```
+
+`--with` 可选的币种有：`usdt-solana`、`usdc-solana`、`usdt-bnb`、`usdc-bnb`、`usdt-ethereum`、`usdc-ethereum`、`usdt-polygon`、`usdc-polygon`、`usdc-base`、`usdc-stellar`、`btc-lightning`。脚本和 agent 必须显式传 `--with`：交互式选择只在终端里出现，而且没有默认币种。
+
+默认情况下它只是打印一个地址，让你用任意钱包去付 —— 不需要私钥，也不需要任何配置。只有当你想让 CLI 改从热钱包签名时才加 `--send`；加 `--json` 输出机器可读格式。
+
+本页剩下的内容就是同一套流程，只不过一步一步来 —— 如果出了问题，或者你想自己写脚本，那才需要看它们。
+
+## 开始之前
+
+- **Node 18 或更高版本**（`node -v`）。别的什么都不用装 —— `npx` 会去拉取 CLI，而克隆下来的
+  `scripts/dist/*.js` 都是自包含的打包产物。
+- **一个钱包**，在你选的链上持有你想用来付款的币种。
+- **那个 Coinbase 链接**，例如
+  `https://payments.coinbase.com/payment-links/pl_01YOURLINKID`。
+- 不需要账号，也不需要 API key。这里用到的每个端点都是公开的。
+
+先设一次：
+
+```bash
+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
+node scripts/dist/quote.js --url "$LINK"
+```
+
+```json
+{
+  "success": true,
+  "merchant": "OpenRouter, Inc.",
+  "invoice": { "amount": "1050.00", "fiat": { "amount": "1050.00", "currency": "USD" } },
+  "callerPays": "1050.00",
+  "coinbaseExpiryIso": "2026-08-09T10:00:00.000Z"
+}
+```
+
+`"success": false` 且带 `LINK_NO_LONGER_PAYABLE`，说明这个链接已被付过或已过期 ——
+去要一个新的，然后停止。
+
+## 2. 创建订单
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+```
+
+这一步不动任何资金，未付款的订单会自然过期。完整充值地址 (deposit address) 在此阶段
+会被**扣留** —— 你只拿到打码后的摘要，先用它核对。
+
+```json
+{
+  "success": true,
+  "rozoPaymentId": "11111111-2222-4333-8444-555555555555",
+  "invoice": { "amount": "1050.000000", "currency": "USD" },
+  "deposit": null,
+  "depositWithheld": true,
+  "display": {
+    "chain": "Solana",
+    "amount": "1054.410000 USDT",
+    "payToMasked": "9WzDXw...AWWM"
+  },
+  "expiry": { "effectiveDeadlineIso": "2026-08-08T11:00:00.000Z", "minutesOfSlack": 55 }
+}
+```
+
+本例即旗舰场景：一张 **$1,050.00** 的账单，用于购买 $1,000 的 OpenRouter 额度。
+任何不超过 **$1,100** 的账单都可以这样支付。
+
+**继续之前务必核对 `display.amount`。** 它通常大于账单金额 —— 因为它包含了跨桥费用和
+网络费用。记下 `rozoPaymentId`；后面每一条命令都要用它。
+
+## 3. 确认
+
+只有在你已经决定付款之后，才带上 `--confirm` 重新执行同一条命令：
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+```
+
+这会释放完整的充值详情，并记录下发送脚本所需的那条确认。
+
+```json
+{
+  "success": true,
+  "confirmed": true,
+  "deposit": {
+    "chain": "Solana",
+    "tokenSymbol": "USDT",
+    "receiverAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+    "receiverMemo": "rozo-901",
+    "amount": "1054.410000",
+    "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+  }
+}
+```
+
+严格按这个信息块给出的字段来发送。对于 Lightning，`deposit.lnInvoice` 里是供扫码的
+BOLT11 字符串，`deposit.amount` 的单位是聪 (satoshis)。
+
+## 4. 付款
+
+### 最简单的方式：用你自己的钱包
+
+**无需私钥、无需环境变量、无需任何配置。** 打开任意一个钱包，严格按上面那个
+`deposit` 信息块所写的去发送：
+
+- `amount` 数量的 `tokenSymbol`，
+- 在 `chain` 这条链上，
+- 发往 `receiverAddress` —— 从 JSON 里复制，绝不要手打重输。
+
+如果这个信息块里还有别的字段，比如 `receiverMemo`，就原样一并带上；在那条链上它属于
+地址的一部分。对于 Lightning，改为扫码或粘贴 `deposit.lnInvoice`。
+
+模式 A 到这里就全部结束了。直接跳到第 5 步。
+
+### 可选的方式：让脚本替你付（模式 B）
+
+只有当你想让这台机器替你签名时才需要，而且只支持 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
+# 用你自己的钱包付款不需要下面任何一项。它们只在你使用 --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>
+
+单笔付款不得超过 **$1,100**；超过就按上面的方式用你自己的钱包付。
+
+```json
+{
+  "success": true,
+  "submitted": true,
+  "confirmed": true,
+  "txHash": "3Bxs4h24hBjHziQ8UJqSjqjbjWQq2sQ3yV9Fq4HrVh5c"
+}
+```
+
+## 5. 观察结清
+
+```bash
+node scripts/dist/status.js --rozo-payment-id <rozoPaymentId> --watch --timeout 600
+```
+
+```json
+{
+  "success": true,
+  "state": "settled",
+  "terminal": true,
+  "payin": { "txHash": "3Bxs4h24...", "confirmedAt": "2026-08-08T10:05:00.000Z" }
+}
+```
+
+状态流转依次为 `awaiting_deposit` → `payin_detected` → `payin_confirmed` →
+`bridging` → `paying_coinbase` → `settled`。你的链上交易被确认**并不**代表结束：
+要一直轮询到 `settled` 为止。
+
+## 出问题时
+
+读 `error.code`。最可能遇到的三个：
+
+| `error.code` | 发生了什么 | 该怎么办 |
+|---|---|---|
+| `LINK_NO_LONGER_PAYABLE` | 这个链接已经被别人付过，或者已过期 | 找商家要一个新链接；不要付任何钱 |
+| `EXPIRY_MARGIN` | 剩余时间太短，不足以安全完成充值、跨桥和结清 | 让订单过期，然后从第 1 步重新开始 |
+| `ALREADY_SENT` | 这个订单已经记录过一次发送 | **不要**再发一次；先跑 `status.js` 并去链上核对 |
+
+**只要已经有钱离开了你的钱包，就绝不要再付一次。** 保留好 `linkId`、
+`rozoPaymentId` 和每一个交易 hash，找人来做对账。向一个一次性充值地址付第二笔款，
+并不保证会被入账。
+
+完整的错误码表在 [README.md](../README.md)，面向 agent 的指令在 [SKILL.md](../SKILL.md)。