@rozoai/checkout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rozo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.es.md

@@ -0,0 +1,192 @@
+# Inicio rápido
+
+[English](QUICKSTART.md) | [简体中文](QUICKSTART.zh.md) | [日本語](QUICKSTART.ja.md) | **Español**
+
+Pagar un enlace de pago de Coinbase (Coinbase Payment Link) de OpenRouter con
+USDT/USDC en Solana, BNB Chain, Ethereum, Polygon, Base o Stellar, o con BTC por
+Lightning. Cinco minutos. Para saber cómo funciona y por qué, ver
+[README.md](README.md).
+
+## El comando de una sola línea
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID --with usdt-solana
+```
+
+Eso ejecuta por uno todos los pasos de abajo: cotizar, crear, revisar, confirmar,
+instrucciones de depósito y luego consultar hasta la liquidación. Monedas para
+`--with`: `usdt-solana`, `usdc-solana`, `usdt-bnb`, `usdc-bnb`, `usdt-ethereum`,
+`usdc-ethereum`, `usdt-polygon`, `usdc-polygon`, `usdc-base`, `usdc-stellar`,
+`btc-lightning`.
+
+Añadir `--send` para pagar desde una billetera caliente en lugar de la propia, y
+`--json` para obtener una salida legible por máquina.
+
+El resto de esta página es el mismo flujo ejecutado paso a paso, que es lo que
+conviene si algo sale mal o si se quiere automatizar por cuenta propia.
+
+## Antes de empezar
+
+- **Node 18 o posterior** (`node -v`). No hay nada más que instalar: `npx`
+  descarga la CLI, y los `scripts/dist/*.js` del repositorio clonado son
+  paquetes autocontenidos.
+- **Una billetera** que tenga la moneda con la que se quiere pagar, en la cadena elegida.
+- **El enlace de Coinbase**, por ejemplo
+  `https://payments.coinbase.com/payment-links/pl_01YOURLINKID`.
+- Sin cuenta y sin clave de API. Todos los endpoints de aquí son públicos.
+
+Definirlo una sola vez:
+
+```bash
+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.
+
+## 1. Cotizarlo (solo lectura, gratis)
+
+```bash
+node scripts/dist/quote.js --url "$LINK"
+```
+
+```json
+{
+  "success": true,
+  "merchant": "OpenRouter, Inc.",
+  "invoice": { "amount": "5.00", "fiat": { "amount": "5.00", "currency": "USD" } },
+  "callerPays": "5.00",
+  "coinbaseExpiryIso": "2026-08-09T10:00:00.000Z"
+}
+```
+
+Un `"success": false` con `LINK_NO_LONGER_PAYABLE` significa que el enlace ya
+está usado o expirado: pedir uno nuevo y detenerse.
+
+## 2. Crear la orden
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT
+```
+
+No se mueve dinero, y una orden sin fondear simplemente expira. La dirección de
+depósito (deposit address) completa se **retiene** en esta etapa: se obtiene un
+resumen enmascarado para revisarlo primero.
+
+```json
+{
+  "success": true,
+  "rozoPaymentId": "11111111-2222-4333-8444-555555555555",
+  "invoice": { "amount": "5.000000", "currency": "USD" },
+  "deposit": null,
+  "depositWithheld": true,
+  "display": {
+    "chain": "Solana",
+    "amount": "5.021000 USDT",
+    "payToMasked": "9WzDXw...AWWM",
+    "memoRequirement": "This deposit REQUIRES the memo/tag below. ..."
+  },
+  "expiry": { "effectiveDeadlineIso": "2026-08-08T11:00:00.000Z", "minutesOfSlack": 55 }
+}
+```
+
+**Revisar `display.amount` antes de continuar.** Normalmente es mayor que la
+factura: incluye las comisiones del puente (bridge) y de la red. Anotar el
+`rozoPaymentId`; todos los comandos posteriores lo usan.
+
+## 3. Confirmar
+
+Solo una vez que se ha decidido pagar, volver a ejecutar el mismo comando con `--confirm`:
+
+```bash
+node scripts/dist/create-order.js --url "$LINK" --chain 900 --token USDT --confirm
+```
+
+Esto libera el detalle completo del depósito y registra la confirmación que
+exigen los scripts de envío.
+
+```json
+{
+  "success": true,
+  "confirmed": true,
+  "deposit": {
+    "chain": "Solana",
+    "tokenSymbol": "USDT",
+    "receiverAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+    "receiverMemo": "rozo-901",
+    "amount": "5.021000",
+    "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+  }
+}
+```
+
+Para Lightning, `deposit.lnInvoice` contiene la cadena BOLT11 que hay que
+escanear, y `deposit.amount` está en satoshis.
+
+## 4. Pagar
+
+Elegir uno. **Modo A** — pagar desde la propia billetera: enviar exactamente
+`deposit.amount` de `deposit.tokenSymbol` a `deposit.receiverAddress`, en
+`deposit.chain`, incluyendo `deposit.receiverMemo` si lo hay. Copiar la
+dirección del JSON; nunca teclearla de nuevo.
+
+**Modo B** — dejar que el script pague desde una billetera caliente (solo EVM y Solana):
+
+```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
+
+# Enviar de verdad. --send es obligatorio.
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+Usar `send-evm.js` con `ROZO_CHECKOUT_EVM_KEY` para Ethereum, BNB Chain,
+Polygon y Base. Topes: $100 por transacción, $200 por sesión.
+
+```json
+{
+  "success": true,
+  "submitted": true,
+  "confirmed": true,
+  "txHash": "3Bxs4h24hBjHziQ8UJqSjqjbjWQq2sQ3yV9Fq4HrVh5c"
+}
+```
+
+## 5. Observar la liquidación
+
+```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" }
+}
+```
+
+Los estados van `awaiting_deposit` → `payin_detected` → `payin_confirmed` →
+`bridging` → `paying_coinbase` → `settled`. Que la transacción on-chain se
+confirme no es el final: seguir consultando hasta `settled`.
+
+## Si algo sale mal
+
+Leer `error.code`. Los tres con los que es más probable toparse:
+
+| `error.code` | Qué ocurrió | Qué hacer |
+|---|---|---|
+| `LINK_NO_LONGER_PAYABLE` | alguien ya pagó el enlace, o expiró | pedir al comercio un enlace nuevo; no pagar nada |
+| `EXPIRY_MARGIN` | queda muy poco tiempo para fondear, puentear y liquidar de forma segura | dejar que la orden expire y volver a empezar desde el paso 1 |
+| `ALREADY_SENT` | ya hay un envío registrado para esta orden | **no** enviar de nuevo; ejecutar `status.js` y revisar primero la cadena |
+
+**Si algo de dinero ya salió de la billetera, nunca pagar de nuevo.** Conservar
+el `linkId`, el `rozoPaymentId` y todos los hashes de transacción, y pedir a una
+persona que lo concilie. No hay garantía de que un segundo pago a una dirección
+de depósito de un solo uso sea acreditado.
+
+La tabla completa de errores está en [README.md](README.md), y las instrucciones
+dirigidas al agente están en [SKILL.md](SKILL.md).

package/QUICKSTART.ja.md

@@ -0,0 +1,187 @@
+# クイックスタート
+
+[English](QUICKSTART.md) | [简体中文](QUICKSTART.zh.md) | **日本語** | [Español](QUICKSTART.es.md)
+
+OpenRouter の Coinbase 決済リンク (Payment Link) を、Solana、BNB Chain、
+Ethereum、Polygon、Base、Stellar 上の USDT/USDC、または Lightning 経由の BTC で支払います。所要 5 分。
+仕組みと設計意図については [README.md](README.md) を参照してください。
+
+## ワンライナー
+
+```bash
+npx @rozoai/checkout pay https://payments.coinbase.com/payment-links/pl_01YOURLINKID --with usdt-solana
+```
+
+これ 1 つで、以下の全ステップを実行します。見積もり、注文作成、確認、承認、入金手順の
+表示、そして決済完了までのポーリングです。`--with` に指定できる通貨: `usdt-solana`、
+`usdc-solana`、`usdt-bnb`、`usdc-bnb`、`usdt-ethereum`、`usdc-ethereum`、
+`usdt-polygon`、`usdc-polygon`、`usdc-base`、`usdc-stellar`、`btc-lightning`。
+
+自分のウォレットではなくホットウォレットから支払う場合は `--send` を、機械可読な出力が
+必要な場合は `--json` を追加してください。
+
+このページの残りは、同じフローを 1 ステップずつ実行するものです。うまくいかないときや、
+自分でスクリプトを書くときは、こちらが必要になります。
+
+## 始める前に
+
+- **Node 18 以降**（`node -v`）。ほかにインストールするものはありません — `npx` が CLI を
+  取得しますし、クローンした `scripts/dist/*.js` は自己完結型のバンドルです。
+- 選んだチェーン上で、支払いたい通貨を保有している**ウォレット**。
+- **Coinbase のリンク**。例:
+  `https://payments.coinbase.com/payment-links/pl_01YOURLINKID`。
+- アカウントも API キーも不要です。ここで使うエンドポイントはすべて公開です。
+
+最初に一度だけ設定します:
+
+```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。
+
+## 1. 見積もりを取得する（読み取り専用、無料）
+
+```bash
+node scripts/dist/quote.js --url "$LINK"
+```
+
+```json
+{
+  "success": true,
+  "merchant": "OpenRouter, Inc.",
+  "invoice": { "amount": "5.00", "fiat": { "amount": "5.00", "currency": "USD" } },
+  "callerPays": "5.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": "5.000000", "currency": "USD" },
+  "deposit": null,
+  "depositWithheld": true,
+  "display": {
+    "chain": "Solana",
+    "amount": "5.021000 USDT",
+    "payToMasked": "9WzDXw...AWWM",
+    "memoRequirement": "This deposit REQUIRES the memo/tag below. ..."
+  },
+  "expiry": { "effectiveDeadlineIso": "2026-08-08T11:00:00.000Z", "minutesOfSlack": 55 }
+}
+```
+
+**先へ進む前に必ず `display.amount` を確認してください。** 通常はインボイス金額より
+大きくなります — ブリッジ (bridge) 手数料とネットワーク手数料が含まれるためです。`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": "5.021000",
+    "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+  }
+}
+```
+
+Lightning の場合、`deposit.lnInvoice` にスキャン用の BOLT11 文字列が入り、
+`deposit.amount` は satoshi 単位になります。
+
+## 4. 支払う
+
+どちらか一方を選びます。**モード A** — 自分のウォレットから支払う: `deposit.chain` 上で、
+`deposit.tokenSymbol` をちょうど `deposit.amount` だけ `deposit.receiverAddress` へ送金します。
+`deposit.receiverMemo` がある場合はそれも付けてください。アドレスは JSON から
+コピーしてください。決して手入力し直さないでください。
+
+**モード B** — スクリプトにホットウォレットから支払わせる（EVM と Solana のみ）:
+
+```bash
+# 署名される内容を正確にプレビューします — 署名は一切行いません
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --dry-run
+
+# 実際に送金します。--send は必須です。
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+Ethereum、BNB Chain、Polygon、Base では `send-evm.js` を `ROZO_CHECKOUT_EVM_KEY` と
+併せて使います。上限: トランザクションごとに $100、セッションごとに $200。
+
+```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` を読んでください。遭遇しやすいのは次の 3 つです:
+
+| `error.code` | 何が起きたか | どうするか |
+|---|---|---|
+| `LINK_NO_LONGER_PAYABLE` | そのリンクは既に誰かが支払ったか、期限切れです | 加盟店に新しいリンクを依頼してください。何も支払わないこと |
+| `EXPIRY_MARGIN` | 入金・ブリッジ・決済完了を安全に行うには残り時間が足りません | その注文は期限切れにさせ、ステップ 1 からやり直してください |
+| `ALREADY_SENT` | この注文に対する送金が既に記録されています | 再送信しては**いけません**。まず `status.js` を実行し、チェーンを確認してください |
+
+**ウォレットから既に資金が出ている場合は、決して二重に支払わないでください。**
+`linkId`、`rozoPaymentId`、すべてのトランザクションハッシュを保管し、人間に照合を
+依頼してください。使い捨ての入金アドレスへの 2 回目の支払いは、入金として反映される
+保証がありません。
+
+エラーコードの完全な一覧は [README.md](README.md) に、エージェント向けの指示は
+[SKILL.md](SKILL.md) にあります。

package/QUICKSTART.md

@@ -0,0 +1,188 @@
+# 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 --with usdt-solana
+```
+
+That runs every step below for you: quote, create, review, confirm, deposit
+instructions, then polling until settlement. 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`.
+
+Add `--send` to pay from a hot wallet rather than your own, 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.
+
+## 1. Quote it (read-only, free)
+
+```bash
+node scripts/dist/quote.js --url "$LINK"
+```
+
+```json
+{
+  "success": true,
+  "merchant": "OpenRouter, Inc.",
+  "invoice": { "amount": "5.00", "fiat": { "amount": "5.00", "currency": "USD" } },
+  "callerPays": "5.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": "5.000000", "currency": "USD" },
+  "deposit": null,
+  "depositWithheld": true,
+  "display": {
+    "chain": "Solana",
+    "amount": "5.021000 USDT",
+    "payToMasked": "9WzDXw...AWWM",
+    "memoRequirement": "This deposit REQUIRES the memo/tag below. ..."
+  },
+  "expiry": { "effectiveDeadlineIso": "2026-08-08T11:00:00.000Z", "minutesOfSlack": 55 }
+}
+```
+
+**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": "5.021000",
+    "payTo": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
+  }
+}
+```
+
+For Lightning, `deposit.lnInvoice` holds the BOLT11 string to scan, and
+`deposit.amount` is in satoshis.
+
+## 4. Pay
+
+Pick one. **Mode A** — pay from your own wallet: send exactly
+`deposit.amount` of `deposit.tokenSymbol` to `deposit.receiverAddress`, on
+`deposit.chain`, including `deposit.receiverMemo` if there is one. Copy the
+address from the JSON; never retype it.
+
+**Mode B** — let the script pay from a hot wallet (EVM and Solana only):
+
+```bash
+# Preview exactly what would be signed — signs nothing
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --dry-run
+
+# Actually send. --send is mandatory.
+ROZO_CHECKOUT_SOL_KEY=<base58 secret key> \
+  node scripts/dist/send-sol.js --rozo-payment-id <rozoPaymentId> --send
+```
+
+Use `send-evm.js` with `ROZO_CHECKOUT_EVM_KEY` for Ethereum, BNB Chain,
+Polygon and Base. Caps: $100 per transaction, $200 per session.
+
+```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).