@billmyagent/x402-express 1.0.0 → 1.1.0

package/README.md

@@ -68,6 +68,15 @@ Coinbase's alike. For a cheap endpoint it is noise. For an expensive one, do the
 cheap part in the handler and the expensive part after you have seen the
 `X-PAYMENT-RESPONSE` header.
 
+## Sandbox keys
+
+A `sk_test_` key settles on **`base-sepolia` only**. The gateway does not offer
+it a live network at all, so a sandbox key configured for `base` fails at
+startup here — when you deploy — rather than when a buyer tries to pay.
+
+Testnet USDC is free from [faucet.circle.com](https://faucet.circle.com). Use a
+`sk_live_` key to take real payments.
+
 ## Networks
 
 `base` and `base-sepolia`, settled in USDC. There is no Ethereum L1
@@ -107,6 +116,7 @@ there is no safe fallback for "where should this money go".
 
 | Message | Cause |
 | --- | --- |
+| `this is a sandbox API key (sk_test_), so it cannot settle on <network>` | A `sk_test_` key is offered testnet only. Use `network: 'base-sepolia'`, or a `sk_live_` key for real funds |
 | `your account has no payout address registered for <network>` | Set one in the dashboard, then restart |
 | `could not reach the facilitator (401 …)` | The API key is wrong, revoked, or its owner's email is unverified |
 | A buyer sees `invalid_exact_evm_payload_recipient_mismatch` | The `payTo` in the request is not your registered address. If you passed `payTo` yourself, that is the mismatch |

package/dist/index.js

@@ -95,6 +95,15 @@ async function resolvePayTo(options) {
     const body = (await res.json());
     const kind = (body.kinds ?? []).find((k) => k.network === network && k.extra?.payTo);
     if (!kind?.extra?.payTo) {
+        // A sandbox key is never OFFERED a live network, so "no payout address"
+        // would be true-shaped and wrong -- the address is registered, the key
+        // just cannot take real money. Read the environment the facilitator
+        // reports rather than guessing from an absence.
+        if (body.environment === 'sandbox') {
+            throw new Error(`@billmyagent/x402-express: this is a sandbox API key (sk_test_), so it cannot settle on ` +
+                `${network}. Use network 'base-sepolia' for testing, or a production key ` +
+                `(sk_live_) to take real payments.`);
+        }
         throw new Error(`@billmyagent/x402-express: your account has no payout address registered for ${network}. ` +
             `Set one in the dashboard under Settings → Payouts, then restart.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billmyagent/x402-express",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Charge for an Express API with x402, settled and reconciled through BillMyAgent",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",