@bitpal/checkout 0.7.0 → 0.9.0

package/README.md

@@ -192,6 +192,88 @@ BitPal may still deliver the **same event more than once** within the window. De
 is not signed, so it is forgeable). Persist the dedup key in the **same transaction** as your side
 effect; handlers must be safe to run twice (UPSERT, not INSERT).
 
+## x402 — charge per API call
+
+A different lane from checkout: no page, no redirect, no deposit address. The caller pays with a
+signed authorization and retries the request. Settles to the **same payout wallet as checkout**
+(register one in the console first).
+
+### Merchant side
+
+```ts
+import { x402 } from '@bitpal/checkout';
+
+// $1.00 USDC per call
+app.get('/report', x402({
+  apiKey: process.env.BITPAL_API_KEY,   // bp_test_… or bp_live_…
+  payTo: '0xYourPayoutWallet',
+  network: 'base',                      // test key → 'base-sepolia'
+  amount: '1.00',                       // human-readable — no decimals math
+}), (req, res) => {
+  res.json({ report: '…' });            // req.x402Payment has the txHash
+});
+```
+
+Unpaid requests get a `402` with the payment terms. Paid ones run `verify` → `settle` and reach your
+handler with `X-PAYMENT-RESPONSE` set. The middleware also does what the API cannot do for you:
+
+- **One payment unlocks one response.** `/settle` is idempotent, so replaying the same `X-PAYMENT`
+  keeps returning success — which would let one payment buy unlimited calls. The middleware records
+  redeemed authorizations and rejects reuse with `409`. Redemption is recorded only once your
+  response actually ships: if the handler throws, the caller can retry with the same header instead
+  of paying for nothing.
+- **Only re-prompts for payment when the money definitely did not move.** `reverted`, `expired` and
+  `failed` get a fresh `402`. Everything else — settlement still in flight, an uncertain broadcast, a
+  timeout — answers `503` and asks for a retry with the *same* header. Handing back a `402` there
+  would make the caller re-sign and pay twice.
+
+Not on Express? `X402Gate` is the framework-neutral core — give it the header and the resource URL,
+it tells you whether to bill or serve. On a `settled` result, call `commit()` once you have delivered
+the response, or `release()` if you could not.
+
+**Two things to set for production:**
+
+- `replayStore` — the default keeps redeemed payments in process memory, so a second instance does
+  not know what the first one served. Pass a shared store (Redis/DB) whose `claim` is an atomic
+  compare-and-set. The memory store also refuses new payments rather than evicting live entries once
+  it fills, so a busy single instance needs a real store too.
+- `resource` — by default it is derived from the request's `Host` header, which the caller controls.
+  The payment binds to that string, so pass an explicit `resource` (or a function) to pin it.
+
+### Payer side
+
+The fee split needs two authorizations, which a stock x402 client does not know about.
+`createX402Payment` reads the `402` and builds both. You supply the signer; the SDK has no crypto
+dependency.
+
+```ts
+import { createX402Payment } from '@bitpal/checkout';
+
+const res = await fetch(url);
+if (res.status === 402) {
+  const { header } = await createX402Payment({
+    requirements: await res.json(),
+    from: account.address,
+    signTypedData: (req) => walletClient.signTypedData({ account, ...req }), // viem
+  });
+  const paid = await fetch(url, { headers: { 'X-PAYMENT': header } });
+}
+```
+
+### Supported
+
+| Network | Token | `network` |
+|---|---|---|
+| Base | USDC | `base` |
+| Base Sepolia | USDC | `base-sepolia` |
+
+Amounts are human-readable (`'1.00'`), the same model as `line_items[].amount` — the server converts.
+Pass `amountAtomic` instead if you already have raw units.
+
+EOA signers only — smart-contract wallets cannot sign EIP-3009 authorizations. Amounts are exact:
+over- and underpayment are both rejected, and this lane has no refund path. Authorizations are valid
+for 90–3600 seconds (the server's floor is 60s; the extra 30s absorbs clock skew and round trips).
+
 ## Config options
 
 ```ts