@rozoai/checkout 0.1.17 → 0.1.19

package/README.md

@@ -388,6 +388,14 @@ keypair or an encrypted keystore, and supports EVM chains and Solana only —
 Stellar and Lightning are Mode A only.
 </details>
 
+## Bulk and automated use
+
+Buying credits regularly, reselling them, or building an agent that tops up
+OpenRouter for its users? The [Bulk Purchases and Agents](https://docs.rozo.ai/products/checkout/bulk-and-agents)
+guide covers the CLI, the MCP server and the raw HTTP flow side by side, plus
+fees, rate limits, idempotency, error codes and what each final status means.
+The batch script below is the CLI half of it.
+
 ## Paying many invoices (batch / resellers)
 
 Each OpenRouter top-up is its own Coinbase link, so paying many is a loop: one
@@ -418,7 +426,8 @@ done < links.txt
 - `--yes` is required when stdin is not a terminal, `--json` prints exactly one
   JSON object, and `--no-watch` returns as soon as the deposit details exist.
   Without `--no-watch`, `pay --json` first waits for settlement (up to
-  `--timeout`, default 900 s) and prints nothing until then, invoice included.
+  `--timeout`, default 900 s; for Lightning, the invoice's remaining validity,
+  at most 60 minutes) and prints nothing until then, invoice included.
 - Without `--send` (the loop above), a successful `pay --no-watch` means the
   order and its deposit details exist. **No money has moved yet**, which is
   why the log says `pending`. With `--send`, the CLI may already have
@@ -511,7 +520,11 @@ a link again, run `status` on its `rozoPaymentId`:
 - `RATE_LIMITED`: order creation is capped per IP per hour (currently 30
   requests, and each `pay` makes two), so plan on about 15 links per hour from
   one IP. Wait for the next hour and resume with the links not yet `settled`.
-  Need more? Email us.
+  Need more? Email us. The CLI retries a 429 by itself, up to 3 times, when
+  the server's `Retry-After` (or `retryAfterSeconds`) fits in 2 minutes of
+  total waiting. A longer wait fails at once: read
+  `error.details.retryAfterSeconds`, and `error.details.rateLimit` (limit,
+  remaining, tier, scope) when the server sends it.
 
 Questions about a batch? Email hi@rozo.ai, or reach us on
 [X](https://x.com/ROZOai) or [Discord](https://discord.gg/EfWejgTbuU).

package/llms.txt

@@ -86,7 +86,8 @@ override; larger invoices go through the keyless path.
 
 Other flags: --yes (skip the interactive confirm; required when stdin is not a
 TTY), --dry-run, --json (exactly one JSON object on stdout), --no-watch,
---timeout <s>. Exit codes: 0 success, 1 refused/failed (read error.code),
+--timeout <s> (default 900; Lightning: the invoice's remaining validity, max 60
+min). Exit codes: 0 success, 1 refused/failed (read error.code),
 2 usage, 3 submitted but unconfirmed.
 
 `pay` withholds the full deposit address until you confirm, then prints it as a
@@ -147,6 +148,39 @@ private key (EVM and Solana only); every other path is keyless.
    only when the router reports paid / coinbase.settled — an intents status of
    payment_completed alone is the bridge lifecycle, not final settlement.
 
+## x402: pay any x402 API from a prepaid balance
+
+For endpoints that answer HTTP 402 with x402 payment requirements. Fund a Rozo
+balance once with the coin you hold, then pay many small x402 calls from it.
+
+  npx @rozoai/checkout x402 topup 20 --with usdt-solana     # one-time deposit address
+  npx @rozoai/checkout x402 pay <url> [--method POST] [--body '...'] [--header 'K: V'] [--max-usd 1.00]
+  npx @rozoai/checkout x402 balance
+
+Payment leg (what the seller receives): USDC on Base (eip155:8453) only,
+scheme "exact". Solana payment leg is coming later. Topup leg: every --with coin above, plus native
+ETH (Ethereum, Base, Arbitrum), BNB and SOL in beta. Native coins never pay a
+seller directly.
+
+Raw HTTP (Authorization: Bearer <agent key ak_...>):
+  POST https://apiserver.mpprouter.dev/v1/x402/topup  {"amount":"20","token":"USDT","chain":"900"}
+       -> one-time deposit address/order; balance is credited after it confirms
+  POST https://apiserver.mpprouter.dev/v1/x402/sign   {"accepts":[<one entry from the 402>],"budget":"1.00","idempotencyKey":"<uuid>"}
+       -> the value for the PAYMENT-SIGNATURE header; replay your request with it
+  POST /v1/x402/keys creates the agent key (returned once). GET /v1/x402/balance.
+
+x402 safety rules:
+- Send the paid request yourself. Never send Rozo your request body, headers or
+  the API keys of the service you are paying; /sign needs only the accepts entry.
+- Generate one idempotencyKey per payment and reuse it on every retry of /sign.
+  A new key on retry can charge twice.
+- Refuse a payment above what the user approved; refuse a payTo on a
+  compromised-wallet list.
+- 503 X402_RETRY, X402_PAYER_MODE_CHANGED or X402_LEDGER_UNAVAILABLE: retry
+  with the same idempotencyKey. Any other 503 from /v1/x402 = "x402 payer not
+  enabled" for this key. Nothing was charged; stop.
+- The agent key owns the balance. Store it 0600, never print or log it.
+
 ## Safety rules (encode these, they prevent fund loss)
 
 - Before paying, require: status == "payment_unpaid" AND source.txHash == null AND
@@ -176,7 +210,9 @@ private key (EVM and Solana only); every other path is keyless.
 
 409 = link already used · 410 = link expired · UNSUPPORTED_SOURCE = the response's
 "supported" object lists valid (chainId, tokenSymbol) pairs (Lightning is supported
-but omitted from that list) · RATE_LIMITED = per-IP creation cap, retry later ·
+but omitted from that list) · RATE_LIMITED = per-IP creation cap, retry later (the CLI itself retries a 429 up
+to 3 times within 2 minutes of total waiting, per Retry-After; a longer wait
+fails at once with error.details.retryAfterSeconds and rateLimit) ·
 INVALID_EMAIL = the optional email is malformed; fix it or omit it.
 
 ## Support

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
   "description": "Pay OpenRouter, or any Coinbase invoice, with the crypto you already hold: USDT/USDC on Solana, BNB Chain, Ethereum or Polygon, USDC on Base or Stellar, or BTC over Lightning. No Coinbase account.",
   "license": "MIT",