@rozoai/checkout 0.1.19 → 0.1.20

package/llms.txt

@@ -158,9 +158,12 @@ balance once with the coin you hold, then pay many small x402 calls from it.
   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.
+scheme "exact". Solana payment leg is coming later. Topup leg: USDT on Solana,
+BNB Chain, Ethereum, Polygon, Arbitrum; USDC on Solana, BNB Chain, Ethereum,
+Polygon, Arbitrum, Base, Stellar. x402 balance top ups accept USDC and USDT only; any other coin
+is answered with 400 X402_TOPUP_SOURCE_UNSUPPORTED. USDT only funds the balance;
+sellers are paid in USDC. Holding a native coin or sats? Use them to top up
+OpenRouter with ROZO Checkout (https://checkout.rozo.ai).
 
 Raw HTTP (Authorization: Bearer <agent key ak_...>):
   POST https://apiserver.mpprouter.dev/v1/x402/topup  {"amount":"20","token":"USDT","chain":"900"}
@@ -177,10 +180,105 @@ x402 safety rules:
 - 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.
+  with the same idempotencyKey. Any other 503 from /v1/x402 means x402 is not
+  available for this key right now. Nothing new was charged; stop. Every server
+  code is listed below.
 - The agent key owns the balance. Store it 0600, never print or log it.
 
+x402 server error codes (returned by https://apiserver.mpprouter.dev/v1/x402/*):
+Every error body looks like
+{"ok":false,"code":"X402_...","error":{"code":"X402_...","message":"..."}},
+sometimes with extra top level fields (limitUsd, balanceUsd, ...).
+These are separate from the codes the CLI raises on its own (X402_UNSUPPORTED,
+X402_OVER_BUDGET, X402_BAD_CHALLENGE, X402_PAYMENT_REJECTED and others). The balance is
+debited only by the ledger commit inside /sign, after signing; every error
+raised before that commit charges nothing. If /sign answers
+X402_LEDGER_UNAVAILABLE or X402_INTERNAL the commit may have landed: retry
+with the same idempotencyKey, and a payment that did land comes back as the
+stored signature (replay:true), never as a second charge.
+The CLI reports every 503 except X402_RETRY, X402_PAYER_MODE_CHANGED and
+X402_LEDGER_UNAVAILABLE as X402_PAYER_DISABLED, with the server code in
+error.details.serverCode. On /sign it retries 429, 500, 502, 504 and those
+three 503 codes itself, with the same idempotencyKey.
+
+balance, topup and sign (keys does not read a key):
+- 401 X402_KEY_INVALID: agent key missing, malformed or unknown. Send
+  "Authorization: Bearer ak_...". Do not mint a new key to get around it: the
+  balance belongs to the old key.
+- 403 X402_KEY_SUSPENDED: the key is not active. Stop; email hi@rozo.ai.
+
+Any route:
+- 503 X402_PAYER_DISABLED: the payer is switched off. Stop, tell the user.
+- 503 X402_PAYER_NOT_CONFIGURED: payer not set up on this deployment. Stop.
+- 503 X402_LEDGER_UNAVAILABLE: ledger unreachable. Retry shortly with the same
+  idempotencyKey.
+- 500 X402_INTERNAL: unexpected error. Retry with the same idempotencyKey a few
+  times, then stop and report it.
+- 405 METHOD_NOT_ALLOWED: wrong HTTP method (keys/topup/sign are POST, balance is GET).
+
+POST /v1/x402/keys:
+- 429 X402_KEY_RATE_LIMITED: too many keys created from this IP this hour.
+  Reuse the key you have, or retry later.
+- 503 X402_RETRY: key collision. Retry.
+
+POST /v1/x402/topup (no deposit address is shown on any error, so nothing can
+be sent to it; only pay an address from a 200 response):
+- 400 X402_INVALID_REQUEST: body is not JSON, or amount is not a USD amount
+  with at most 2 decimals.
+- 400 X402_TOPUP_AMOUNT_OUT_OF_RANGE: top up must be between $5 and $500.
+- 400 X402_TOPUP_SOURCE_REQUIRED: say which coin you pay with: chain and
+  token. The response lists accepted chains.
+- 400 X402_UNSUPPORTED_CHAIN: unknown chain. Use a CAIP-2 id or a name such as
+  solana, base, ethereum, bsc, polygon, arbitrum, stellar.
+- 400 X402_TOPUP_SOURCE_UNSUPPORTED: that coin is not accepted for top ups.
+  Use USDC or USDT. May carry a "supported" list.
+- 502 INTENTS_API_FAILED: the top up order could not be created. Retry later.
+- 503 X402_TOPUP_MISCONFIGURED or X402_TOPUP_NOT_REGISTERED: the order was not
+  usable, the address was withheld. Retry later; email hi@rozo.ai if it repeats.
+- 503 X402_PAYER_SHADOW, X402_TOPUP_NOT_CONFIGURED or X402_SIGNER_NOT_CONFIGURED:
+  top ups are closed right now. Stop.
+
+POST /v1/x402/sign:
+- 400 X402_INVALID_REQUEST: body is not JSON, or budget is not a positive USD amount.
+- 400 X402_IDEMPOTENCY_KEY_REQUIRED: send idempotencyKey, 8 to 128 chars of
+  [A-Za-z0-9_.:-], one per 402 challenge.
+- 400 X402_UNSUPPORTED_VERSION: only x402Version 2 is accepted.
+- 400 X402_UNSUPPORTED_NETWORK, X402_UNSUPPORTED_SCHEME, X402_UNSUPPORTED_ASSET,
+  X402_INVALID_REQUIREMENT or X402_SIGN_UNSUPPORTED: the accepts entry is
+  malformed or asks for something not covered (only exact USDC is signed).
+  Do not retry the same entry; tell the user.
+- 402 X402_BUDGET_EXCEEDED: the challenge asks more than your budget. Stop and
+  ask the user.
+- 402 X402_PER_TX_LIMIT_EXCEEDED: above this key's single-payment limit
+  (limitUsd). Stop and ask the user.
+- 402 X402_INSUFFICIENT_BALANCE: balance too low (balanceUsd). Top up, wait
+  for the credit, then pay again.
+- 403 X402_PAYTO_NOT_ALLOWED: payTo is not on this key's allowlist. Stop.
+- 403 X402_PAYTO_BLOCKED: this payTo is blocked. Stop, do not retry.
+- 409 X402_IDEMPOTENCY_CONFLICT: this idempotencyKey was already used for a
+  different requirement. Nothing new was charged. Use a new key only for a new
+  402 challenge.
+- 410 X402_CREDENTIAL_REFUNDED: the stored signature expired unused and its
+  amount went back to the balance. Fetch a new 402 and sign it with a new key.
+- 429 X402_DAILY_LIMIT_EXCEEDED: this key's daily limit would be exceeded
+  (limitUsd, spentTodayUsd). Wait for the daily
+  window to reset, or ask hi@rozo.ai for a higher limit.
+- 429 X402_GLOBAL_DAILY_CAP_REACHED or X402_SIGNER_DAILY_CAP_REACHED: a
+  platform-wide daily cap was reached. Retry after 00:00 UTC.
+- 429 X402_SIGNER_CAP_REACHED: the signing service refused this amount. Try a
+  smaller payment or later.
+- 503 X402_RETRY or X402_PAYER_MODE_CHANGED: transient. Retry with the same
+  idempotencyKey.
+- 503 X402_PAYER_SHADOW: the payer is not live for this key. A fresh request
+  was checked and recorded but not signed, and nothing was charged. With
+  "replay":true it refers to an earlier payment under this idempotencyKey,
+  which may have been charged: check /balance, never pay again with a new key.
+  Stop.
+- 503 X402_SIGNER_NOT_CONFIGURED or X402_SIGNER_DISABLED: signing for this
+  network is off right now. Stop.
+A 200 with "replay":true is the stored signature for an idempotencyKey that
+was already paid; it is not a second charge.
+
 ## Safety rules (encode these, they prevent fund loss)
 
 - Before paying, require: status == "payment_unpaid" AND source.txHash == null AND

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rozoai/checkout",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "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",

package/scripts/dist/cli.js

@@ -58225,8 +58225,9 @@ USAGE
 
 TOPUP COINS (--with)
   usdt-solana usdc-solana usdt-bnb usdc-bnb usdt-ethereum usdc-ethereum
-  usdt-polygon usdc-polygon usdc-base usdc-stellar btc-lightning
-  native (beta): eth-ethereum eth-base eth-arbitrum bnb-bnb sol-solana
+  usdt-polygon usdc-polygon usdt-arbitrum usdc-arbitrum usdc-base usdc-stellar
+  x402 top ups accept USDC and USDT only. Holding a native coin or sats?
+  Use them to top up OpenRouter with ROZO Checkout (rozo-checkout pay).
 
 PAY OPTIONS
   --method <m>            HTTP method (default GET)
@@ -58563,18 +58564,26 @@ var TOPUP_PRESETS = {
   "usdc-ethereum": { chain: "1", token: "USDC" },
   "usdt-polygon": { chain: "137", token: "USDT" },
   "usdc-polygon": { chain: "137", token: "USDC" },
+  "usdt-arbitrum": { chain: "42161", token: "USDT" },
+  "usdc-arbitrum": { chain: "42161", token: "USDC" },
   "usdc-base": { chain: "8453", token: "USDC" },
-  "usdc-stellar": { chain: "1500", token: "USDC" },
-  "btc-lightning": { chain: "lightning", token: "BTC" },
-  "eth-ethereum": { chain: "1", token: "ETH", native: true },
-  "eth-base": { chain: "8453", token: "ETH", native: true },
-  "eth-arbitrum": { chain: "42161", token: "ETH", native: true },
-  "bnb-bnb": { chain: "56", token: "BNB", native: true },
-  "sol-solana": { chain: "900", token: "SOL", native: true }
+  "usdc-stellar": { chain: "1500", token: "USDC" }
 };
+var NON_TOPUP_PRESETS = /* @__PURE__ */ new Set([
+  "btc-lightning",
+  "eth-ethereum",
+  "eth-base",
+  "eth-arbitrum",
+  "bnb-bnb",
+  "sol-solana"
+]);
+var TOPUP_STABLE_ONLY = "x402 top ups accept USDC and USDT only. Holding a native coin or sats? Use them to top up OpenRouter with: rozo-checkout pay <openrouter-payment-link> --with btc-lightning (sats), or https://checkout.rozo.ai (native coins).";
 var TOPUP_MIN_USD = 5;
 function resolveTopupPreset(value) {
   const key = String(value ?? "").trim().toLowerCase();
+  if (NON_TOPUP_PRESETS.has(key) || /^(eth|bnb|sol|pol|matic|xlm|btc|sats)-/.test(key)) {
+    throw new SkillError("X402_TOPUP_SOURCE_UNSUPPORTED", TOPUP_STABLE_ONLY, { preset: key });
+  }
   const hit = TOPUP_PRESETS[key];
   if (!hit) {
     throw new SkillError(
@@ -58753,7 +58762,6 @@ async function runTopup({ amountUsd, coin }, { fetchImpl, blacklist } = {}) {
     ...created ? { keyCreated: created } : {},
     key: { masked: maskKey(found.key), source: found.source },
     coin: preset.preset,
-    native: Boolean(preset.native),
     requestedUsd: String(amountUsd).trim(),
     deposit,
     note: "Send exactly once, from your own wallet. Your x402 balance is credited after the deposit confirms."