@curless/agentbank-merchant-sdk 0.6.0 → 0.6.1

package/README.md

@@ -5,19 +5,22 @@ Drop into a merchant's backend (Shopify storefront, ClubMed booking flow,
 TikTok Shop seller service, anything that wants to **accept agent payments**)
 and you get:
 
-- **`checkout.open`** — the fast path. **You** price an order from your own catalog and open a checkout; an agent pays it; the money lands in your account. agentbank never stores your catalog — the price you pass is authoritative. You accept every agent-payment protocol (ACP, x402, A2A, UCP, AP2, …) with zero protocol code.
+- **`checkout.openACP`** — merchant-quoted **card** checkout. **You** price an order from your own catalog and open a checkout; an agent pays it with a card credential; the money lands in your account.
+- **`checkout.openX402`** — merchant-quoted **USDC (x402)** checkout. You set the authoritative USDC amount; the gateway freezes it and returns the x402 challenge; a buyer agent signs an EIP-3009 authorization and pays `{ sessionId }` on-chain. Settlement is on Base (mainnet or Sepolia, decided by your account/key) — your USDC lands at your address. The stablecoin twin of `openACP`.
+- **`orders`** — read your settled orders: `orders.list({ status, protocol, currency, from, to, limit, offset })` (filtered + paginated, with a total), `orders.get(id)` (one order in full + the card it was paid with), `orders.summary({…})` (count + gross by currency + breakdowns by protocol/status — a dashboard in one call).
 - **`AgentbankMerchant`** — typed client; also exposes `PaymentIntents` (create/get/capture/list/ledger-entries across ACP / x402 / AP2 / UCP / A2A), `PaymentLinks`, `Customers`, `BalanceTransactions`, and `WebhookEndpoints`. No refund method — refunds are Curless-originated (see below).
 - **`verifyWebhook` / `parseVerifiedWebhook`** — HMAC-SHA256 signature verification (Stripe-style `t=…,v1=…`), constant-time, **edge-safe** (Web Crypto, runs on Vercel Edge / Cloudflare Workers). Async — `await` them.
-- **`x402`** — `buildChallenge()` to emit your own canonical 402 from your route, `decodeXPaymentHeader()` to parse what the agent paid with.
+- **`x402`** — emit/parse payments yourself (`buildChallenge()`, `decodeXPaymentHeader()`) **plus zero-crypto-knowledge helpers**: `usdc(network)` (contract + EIP-712 domain + decimals — no hardcoded hex), `isMainnet/isTestnet(network)`, `explorerTxUrl(network, txHash)` (a basescan / sepolia.basescan receipt link), `formatUsdc(baseUnits)` (exact 6-dp string, no float drift).
 
-One runtime dependency (`@curless/agentbank-core`, for portable crypto + the HTTP layer). **Edge-safe** — Web Crypto only, no `node:` builtins. Node 18+.
+agentbank never stores your catalog — the price you pass is authoritative, and you accept every agent-payment protocol with zero protocol code. One runtime dependency (`@curless/agentbank-core`). **Edge-safe** — Web Crypto only, no `node:` builtins. Node 18+.
 
 > **Refunds**: agentbank exposes no refund-initiation endpoint. The merchant
-> refunds in Curless (it holds the money); Curless executes the card refund and
-> forwards the event, which advances the PI to `refunded` / `partially_refunded`.
-> Read the resulting state via `paymentIntents.get()` / `.list()`.
+> refunds in Curless (it holds the money); Curless executes the refund and
+> forwards the event, which advances the order/PI to `refunded` /
+> `partially_refunded`. Read the resulting state via `orders.list({ status:
+> 'refunded' })` or `paymentIntents.get()`.
 
-### Fast path — open a merchant-quoted checkout
+## Fast path — open a merchant-quoted checkout
 
 ```ts
 import { AgentbankMerchant } from '@curless/agentbank-merchant-sdk';
@@ -28,30 +31,58 @@ const agentbank = new AgentbankMerchant({
   merchantId: process.env.AGENTBANK_MERCHANT_ID!,
 });
 
-// In your "an agent wants to buy" handler: YOU set the price.
-const checkout = await agentbank.checkout.open({
+// CARD (ACP) — YOU set the price; an agent pays it; money lands in your account.
+const checkout = await agentbank.checkout.openACP({
   currency: 'EUR',
-  items: [
-    { sku: 'resort-bali', name: 'Club Med Bali — 7 nights', quantity: 1, unitPrice: 192000 },
-  ],
+  items: [{ sku: 'resort-bali', name: 'Club Med Bali — 7 nights', quantity: 1, unitPrice: 192000 }],
 });
-
-// Hand checkout.id back to the buyer agent; it pays, money lands in your account.
 return { checkoutId: checkout.id, amount: checkout.amount, currency: checkout.currency };
+
+// USDC (x402) — YOU set the USDC amount (base units, 6 dp). Hand the challenge
+// to the buyer agent; it signs + pays `{ sessionId }` on-chain. The network
+// (base / base-sepolia) is decided by your account — same code on testnet/mainnet.
+const x402co = await agentbank.checkout.openX402({
+  amount: 1_050_000, // 1.05 USDC
+  items: [{ sku: 'resort-bali', name: 'Club Med Bali — 7 nights', quantity: 1, unitPrice: 1_050_000 }],
+});
+return { sessionId: x402co.sessionId, accepts: x402co.accepts, network: x402co.network };
+```
+
+That's the whole integration: install, set three env vars, call one method. You
+stay the source of truth for your catalog and prices — nothing to sync.
+
+## Read your orders
+
+```ts
+// Filtered + paginated (status / protocol / currency / date range):
+const { data, pagination } = await agentbank.orders.list({ status: 'paid', protocol: 'x402', limit: 50 });
+
+// One order in full (line items + the card it was paid with):
+const { order, payment } = await agentbank.orders.get(data[0]!.id);
+
+// A dashboard in one call: count + gross by currency + by protocol/status.
+const summary = await agentbank.orders.summary({ from: '2026-06-01' });
+// summary.count · summary.byCurrency[{ currency, count, totalAmount }] · summary.byProtocol · summary.byStatus
 ```
 
-That's the whole integration: install, set three env vars, call `checkout.open`.
-You stay the source of truth for your catalog and prices — nothing to sync.
+## x402 helpers — display a settled payment, zero crypto knowledge
+
+```ts
+import { x402 } from '@curless/agentbank-merchant-sdk';
+
+x402.explorerTxUrl('base', '0xa596…');  // → https://basescan.org/tx/0xa596…  (sepolia.basescan on testnet)
+x402.formatUsdc(1_050_000);             // → "1.050000"   (exact string math, no float drift)
+x402.formatUsdc(1_050_000, { symbol: true }); // → "1.050000 USDC"
+x402.isMainnet('base');                 // → true       (isTestnet('base-sepolia') → true)
+x402.usdc('base')!.contract;            // → "0x833589…02913"  (no hardcoded hex)
+```
 
-### Lower-level — PaymentIntents, webhooks, x402
+## Lower-level — PaymentIntents, webhooks, self-emitted 402
 
 ```ts
 import { AgentbankMerchant, parseVerifiedWebhook, x402 } from '@curless/agentbank-merchant-sdk';
 
-const client = new AgentbankMerchant({
-  baseUrl: 'https://api.agentbank.dev',
-  apiKey: process.env.AGENTBANK_KEY!, // merchant:write
-});
+const client = new AgentbankMerchant({ baseUrl: 'https://mcp.curless.ai', apiKey: process.env.AGENTBANK_KEY! });
 
 // Create a PaymentIntent the agent will pay against
 const pi = await client.paymentIntents.create({
@@ -71,14 +102,22 @@ const event = await parseVerifiedWebhook(
   req.headers['x-agentbank-signature'],
 );
 
-// Or emit your own 402 challenge from your route
-return new Response(JSON.stringify(x402.buildChallenge({
-  asset: '0x036CbD…F7e',         // base-sepolia USDC
-  network: 'base-sepolia',
-  payTo: '0xMerchantAddr',
-  amount: '6200000',              // 6.20 USDC
-  resource: 'https://shop.example/api/checkout',
-})), { status: 402, headers: { 'content-type': 'application/json' } });
+// Or emit your own 402 challenge from your route. buildChallenge auto-fills the
+// right EIP-712 domain per network ("USD Coin" on base, "USDC" on base-sepolia)
+// — a wrong name reverts on-chain, so let the helper get it right.
+const usdc = x402.usdc('base')!;
+return new Response(
+  JSON.stringify(
+    x402.buildChallenge({
+      asset: usdc.contract,   // no hardcoded hex
+      network: 'base',
+      payTo: '0xYourUsdcAddress',
+      amount: '1050000',      // 1.05 USDC (6 dp)
+      resource: 'https://shop.example/api/checkout',
+    }),
+  ),
+  { status: 402, headers: { 'content-type': 'application/json' } },
+);
 ```
 
 ## Timeouts & errors

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@curless/agentbank-merchant-sdk",
-  "version": "0.6.0",
-  "description": "Merchant-side SDK for agentbank — accept agent payments: open a merchant-quoted checkout (you price it, an agent pays it), PaymentIntents, edge-safe webhook verification, x402 challenge helpers.",
+  "version": "0.6.1",
+  "description": "Merchant-side SDK for agentbank — accept agent payments: open a merchant-quoted card (ACP) or USDC (x402) checkout you price, list/summarize orders, PaymentIntents, edge-safe webhook verification, and x402 helpers.",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",