@bitpal/checkout 0.6.0 → 0.8.0

package/README.md

@@ -63,10 +63,16 @@ shows the per-order deposit address + QR, and confirms the payment on-chain.
 ```ts
 const { data: session } = await bitpal.checkout.createSession({
   line_items: [
-    { name: 'Pro Plan', amount: '29', currency: 'USDC' },  // just the USD number
+    { name: 'Pro Plan', amount: '29', currency: 'USDC' },  // `currency` = price denomination (USD via USDC)
+  ],
+  // Payment options the buyer may choose — (chain, token) pairs. Mix tokens freely.
+  //   `chain` accepts a short-name ('base' | 'arbitrum' | 'bnb' | 'tron' | 'solana') or a CAIP-2 id;
+  //   it resolves to the right testnet/mainnet chain for your mode (test vs live key) automatically.
+  allowed_assets: [
+    { chain: 'base',   token: 'USDC' },
+    { chain: 'tron',   token: 'USDT' },
+    { chain: 'solana', token: 'USDC' },
   ],
-  pay_chain: 'eip155:84532',     // Base Sepolia (test mode). Live mode: 'eip155:8453' (Base mainnet).
-                                 // Or use allowed_pay_chains for a buyer-picked chain.
   expires_in_seconds: 1800,
   success_url: 'https://yourstore.com/thanks',
 });
@@ -75,7 +81,13 @@ const { data: session } = await bitpal.checkout.createSession({
 redirect(session.checkout_url!);
 ```
 
-`pay_chain` (single fixed chain) and `allowed_pay_chains` (buyer picks) are mutually exclusive.
+**Setting the payment options** (precedence, highest first):
+
+- **`allowed_assets`** — `(chain, token)` cells. The standard, most explicit way; the buyer picks any listed pair (lets you mix tokens, e.g. USDC on Base + USDT on Tron).
+- `allowed_pay_chains: string[]` — shorthand for "the line-item `currency` across these chains" (one token, many chains).
+- `pay_chain: string` — a single fixed chain, no buyer choice.
+
+`pay_chain` and `allowed_pay_chains` are mutually exclusive; `allowed_assets` takes precedence over both. Omit all three and it defaults to **one chain × the line-item currency**. `currency` on the line item is always the **price denomination** (what the amount is quoted in) — independent of which token the buyer pays with.
 
 ### Self-hosted flow: issue a deposit address yourself
 
@@ -89,7 +101,7 @@ const { data } = await bitpal.checkout.issueDepositAddress(session.id, {
   session_token: session.session_token!, // from createSession
   refundAddress: '0xBuyerWallet...',      // VM-matched (EVM 0x… / Tron T… / Solana base58); committed, immutable after issuance
   chain: 'eip155:84532',                  // match the session's chain (test: Base Sepolia / live: eip155:8453).
-                                          // only needed for multi-option (allowed_pay_chains) sessions
+                                          // only needed for multi-option (allowed_assets / allowed_pay_chains) sessions
   token: 'USDC',
 });
 
@@ -180,6 +192,85 @@ 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: '1000000',                    // atomic (USDC, 6dp) — your gross; the fee comes out of it
+}), (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` |
+
+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