@billmyagent/x402-express 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# @billmyagent/x402-express
+
+Charge for an Express API with [x402](https://x402.org), settled and reconciled through BillMyAgent.
+
+```bash
+npm install @billmyagent/x402-express express
+```
+
+```js
+import express from 'express';
+import { paymentMiddleware } from '@billmyagent/x402-express';
+
+const app = express();
+
+app.use(
+  await paymentMiddleware({
+    apiKey: process.env.BILLMYAGENT_API_KEY,
+    network: 'base',
+    routes: {
+      'GET /premium': { price: '$0.01', config: { description: 'Premium data' } },
+    },
+  })
+);
+
+app.get('/premium', (_req, res) => res.json({ ok: true }));
+app.listen(4021);
+```
+
+`GET /premium` now answers `402 Payment Required` until a caller presents a valid
+x402 payment. Any x402 client pays it automatically —
+[`@billmyagent/payments-core`](../core), `x402-axios`, `x402-fetch`, or an agent
+framework that speaks the protocol.
+
+## What this adds over `x402-express`
+
+This is a thin wrapper over Coinbase's official middleware. It does two things
+that one cannot.
+
+**It routes the payment through BillMyAgent's facilitator**, authenticated with
+your API key. Every payment your API takes is then recorded, checked against the
+chain by the reconciler, and visible in your dashboard. Without it, payments
+happen entirely between the buyer and Coinbase's facilitator and you have no
+record beyond your own logs.
+
+**It resolves your payout address from your account** instead of asking you to
+paste it into your server config. `payTo` is an address that decides where money
+goes. A typo in an environment variable sends a real payment to a stranger, and
+it looks like a successful transfer from every side. Reading it from the account
+you registered — the same address the facilitator checks every payment against
+before broadcasting — means the value can only be wrong in one place, where you
+can see and fix it.
+
+## Non-custodial
+
+The buyer's signed EIP-3009 authorization transfers USDC to **your** address
+directly. BillMyAgent never holds the funds and never appears in the transaction.
+The platform fee is a separate accrual against a settlement the reconciler has
+independently confirmed on-chain — it is not deducted from the transfer.
+
+## Timing: your handler runs before settlement
+
+The x402 middleware verifies the payment, runs your route handler, and settles
+afterwards. So a settlement that fails means you already served that response for
+free.
+
+This is how the protocol works and is identical with every facilitator, ours and
+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.
+
+## Networks
+
+`base` and `base-sepolia`, settled in USDC. There is no Ethereum L1
+settlement. Register a payout address for the network you want in the dashboard
+under **Settings → Payouts** before your first paid request.
+
+Use `base-sepolia` to develop against free testnet USDC.
+
+## API
+
+### `paymentMiddleware(options)`
+
+Returns a `Promise<RequestHandler>`. Await it once at startup — the payout
+address is resolved then, so a misconfigured account fails at deploy rather than
+when a buyer arrives.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `apiKey` | required | Your BillMyAgent API key |
+| `routes` | required | `{ 'GET /path': { price: '$0.01' } }`, or `{ '/path': '$0.01' }` |
+| `network` | `'base'` | Default chain for routes that do not name one |
+| `baseUrl` | `https://api.billmyagent.ai` | Gateway to talk to |
+| `payTo` | resolved | Override the payout address and skip the lookup |
+| `paywall` | – | Passed through to the official browser paywall page |
+
+### `facilitator({ apiKey, baseUrl })`
+
+The `FacilitatorConfig` on its own, if you would rather call the official
+`paymentMiddleware` yourself and keep your own `payTo`.
+
+### `resolvePayTo({ apiKey, baseUrl, network })`
+
+The payout address registered for a network. Throws if none is registered —
+there is no safe fallback for "where should this money go".
+
+## Errors you might see
+
+| Message | Cause |
+| --- | --- |
+| `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 |
+| A buyer sees `duplicate_settlement` | That authorization was already settled. The client should sign a fresh one |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Charge for your Express API with x402, settled through BillMyAgent.
+ *
+ * This is a thin wrapper over the official `x402-express` middleware. It does
+ * exactly two things the official one cannot:
+ *
+ *   1. Points the facilitator at BillMyAgent and authenticates with your API
+ *      key, so the payments your API takes are recorded, reconciled against the
+ *      chain, and visible in your dashboard.
+ *   2. Resolves your payout address from your account instead of asking you to
+ *      paste it into your server config.
+ *
+ * The second one matters more than it looks. `payTo` is an address inside a
+ * request that decides where money goes; a typo in an environment variable is a
+ * payment sent to a stranger, and it looks like a successful transfer from every
+ * side. Resolving it from the address you registered — the same one the
+ * facilitator checks every payment against before broadcasting — means the
+ * value can only be wrong in one place, where you can fix it.
+ *
+ * Non-custodial: the buyer's signed transfer pays your address directly.
+ * BillMyAgent never holds the funds and never appears in the transaction.
+ *
+ *   import express from 'express';
+ *   import { paymentMiddleware } from '@billmyagent/x402-express';
+ *
+ *   const app = express();
+ *   app.use(await paymentMiddleware({
+ *     apiKey: process.env.BILLMYAGENT_API_KEY!,
+ *     network: 'base',
+ *     routes: { 'GET /premium': { price: '$0.01' } },
+ *   }));
+ *
+ * ONE THING TO KNOW ABOUT TIMING
+ *
+ * The official middleware runs YOUR handler before it settles. So a settlement
+ * that fails means you already served that response for free. That is how the
+ * x402 protocol works and is the same with every facilitator, BillMyAgent's and
+ * Coinbase's alike. For a cheap endpoint it is noise; for an expensive one,
+ * verify first and do the expensive part after.
+ */
+import type { RequestHandler } from 'express';
+import type { FacilitatorConfig, Network, PaywallConfig, RouteConfig, RoutesConfig } from 'x402/types';
+/** The production facilitator. Override for a local gateway. */
+export declare const DEFAULT_BASE_URL = "https://api.billmyagent.ai";
+/** Networks BillMyAgent settles. There is deliberately no Ethereum L1. */
+export type SupportedNetwork = 'base' | 'base-sepolia';
+export interface FacilitatorOptions {
+    /** Your BillMyAgent API key (the same `X-API-Key` the REST API takes). */
+    apiKey: string;
+    /** Gateway base URL. Defaults to production. */
+    baseUrl?: string;
+}
+/**
+ * A `FacilitatorConfig` pointed at BillMyAgent.
+ *
+ * Exported on its own so you can pass it to the official `paymentMiddleware`
+ * directly if you would rather keep your own `payTo` and skip the resolution
+ * step. Everything else in this package is built on it.
+ */
+export declare function facilitator({ apiKey, baseUrl }: FacilitatorOptions): FacilitatorConfig;
+/**
+ * Ask the gateway which payout address it will settle to on a network.
+ *
+ * This is the address you registered in your BillMyAgent account. The
+ * facilitator refuses any payment whose `payTo` does not match it, so reading it
+ * from here rather than declaring it locally removes the only way those two can
+ * disagree.
+ *
+ * Throws rather than defaulting: there is no safe fallback for "where should
+ * this money go".
+ */
+export declare function resolvePayTo(options: FacilitatorOptions & {
+    network: SupportedNetwork;
+}): Promise<string>;
+/** A route price, with the network filled in for you. */
+export type BillMyAgentRouteConfig = Omit<RouteConfig, 'network'> & {
+    network?: SupportedNetwork;
+};
+export interface PaymentMiddlewareOptions extends FacilitatorOptions {
+    /** Which chain to settle on. Default 'base'. */
+    network?: SupportedNetwork;
+    /**
+     * Routes to charge for, in the official shape — `{ 'GET /premium': { price:
+     * '$0.01' } }` — except that `network` is optional and defaults to the one
+     * above.
+     */
+    routes: Record<string, BillMyAgentRouteConfig | string>;
+    /**
+     * Payout address override. Normally omitted: leaving it out resolves the
+     * address from your account, which is the whole point of this wrapper. Supply
+     * it only when you need the middleware to start without a network call.
+     */
+    payTo?: string;
+    /** Passed through to the official middleware's paywall page. */
+    paywall?: PaywallConfig;
+}
+/**
+ * Build the Express middleware.
+ *
+ * Async because it resolves your payout address before serving anything. Doing
+ * it at startup rather than on the first paid request means a misconfigured
+ * account fails when you deploy, not when a buyer arrives.
+ */
+export declare function paymentMiddleware(options: PaymentMiddlewareOptions): Promise<RequestHandler>;
+export type { FacilitatorConfig, Network, PaywallConfig, RouteConfig, RoutesConfig };

package/dist/index.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Charge for your Express API with x402, settled through BillMyAgent.
+ *
+ * This is a thin wrapper over the official `x402-express` middleware. It does
+ * exactly two things the official one cannot:
+ *
+ *   1. Points the facilitator at BillMyAgent and authenticates with your API
+ *      key, so the payments your API takes are recorded, reconciled against the
+ *      chain, and visible in your dashboard.
+ *   2. Resolves your payout address from your account instead of asking you to
+ *      paste it into your server config.
+ *
+ * The second one matters more than it looks. `payTo` is an address inside a
+ * request that decides where money goes; a typo in an environment variable is a
+ * payment sent to a stranger, and it looks like a successful transfer from every
+ * side. Resolving it from the address you registered — the same one the
+ * facilitator checks every payment against before broadcasting — means the
+ * value can only be wrong in one place, where you can fix it.
+ *
+ * Non-custodial: the buyer's signed transfer pays your address directly.
+ * BillMyAgent never holds the funds and never appears in the transaction.
+ *
+ *   import express from 'express';
+ *   import { paymentMiddleware } from '@billmyagent/x402-express';
+ *
+ *   const app = express();
+ *   app.use(await paymentMiddleware({
+ *     apiKey: process.env.BILLMYAGENT_API_KEY!,
+ *     network: 'base',
+ *     routes: { 'GET /premium': { price: '$0.01' } },
+ *   }));
+ *
+ * ONE THING TO KNOW ABOUT TIMING
+ *
+ * The official middleware runs YOUR handler before it settles. So a settlement
+ * that fails means you already served that response for free. That is how the
+ * x402 protocol works and is the same with every facilitator, BillMyAgent's and
+ * Coinbase's alike. For a cheap endpoint it is noise; for an expensive one,
+ * verify first and do the expensive part after.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BASE_URL = void 0;
+exports.facilitator = facilitator;
+exports.resolvePayTo = resolvePayTo;
+exports.paymentMiddleware = paymentMiddleware;
+const x402_express_1 = require("x402-express");
+/** The production facilitator. Override for a local gateway. */
+exports.DEFAULT_BASE_URL = 'https://api.billmyagent.ai';
+/**
+ * A `FacilitatorConfig` pointed at BillMyAgent.
+ *
+ * Exported on its own so you can pass it to the official `paymentMiddleware`
+ * directly if you would rather keep your own `payTo` and skip the resolution
+ * step. Everything else in this package is built on it.
+ */
+function facilitator({ apiKey, baseUrl = exports.DEFAULT_BASE_URL }) {
+    if (!apiKey) {
+        throw new Error('@billmyagent/x402-express: apiKey is required');
+    }
+    const url = `${baseUrl.replace(/\/+$/, '')}/api/v1/x402`;
+    const headers = { 'X-API-Key': apiKey };
+    return {
+        url: url,
+        // Called per request by the official client, which is why this is a
+        // function rather than a static header map: it lets a key be rotated
+        // without a restart if you close over a mutable value.
+        createAuthHeaders: async () => ({
+            verify: { ...headers },
+            settle: { ...headers },
+            supported: { ...headers },
+            list: { ...headers },
+        }),
+    };
+}
+/**
+ * Ask the gateway which payout address it will settle to on a network.
+ *
+ * This is the address you registered in your BillMyAgent account. The
+ * facilitator refuses any payment whose `payTo` does not match it, so reading it
+ * from here rather than declaring it locally removes the only way those two can
+ * disagree.
+ *
+ * Throws rather than defaulting: there is no safe fallback for "where should
+ * this money go".
+ */
+async function resolvePayTo(options) {
+    const { apiKey, baseUrl = exports.DEFAULT_BASE_URL, network } = options;
+    const url = `${baseUrl.replace(/\/+$/, '')}/api/v1/x402/supported`;
+    const res = await fetch(url, { headers: { 'X-API-Key': apiKey } });
+    if (!res.ok) {
+        throw new Error(`@billmyagent/x402-express: could not reach the facilitator (${res.status} ${res.statusText}). ` +
+            `Check BILLMYAGENT_API_KEY and that ${baseUrl} is correct.`);
+    }
+    const body = (await res.json());
+    const kind = (body.kinds ?? []).find((k) => k.network === network && k.extra?.payTo);
+    if (!kind?.extra?.payTo) {
+        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.`);
+    }
+    return kind.extra.payTo;
+}
+/**
+ * Build the Express middleware.
+ *
+ * Async because it resolves your payout address before serving anything. Doing
+ * it at startup rather than on the first paid request means a misconfigured
+ * account fails when you deploy, not when a buyer arrives.
+ */
+async function paymentMiddleware(options) {
+    const network = options.network ?? 'base';
+    const payTo = options.payTo ?? (await resolvePayTo({ ...options, network }));
+    const routes = {};
+    for (const [pattern, value] of Object.entries(options.routes)) {
+        const config = typeof value === 'string' ? { price: value } : value;
+        // Object.assign rather than a spread into a fresh literal so a route that
+        // names its own network keeps it: a merchant charging in two places on two
+        // chains is a real configuration, not a mistake to normalise away.
+        routes[pattern] = { network, ...config };
+    }
+    return (0, x402_express_1.paymentMiddleware)(payTo, routes, facilitator(options), options.paywall);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@billmyagent/x402-express",
+  "version": "1.0.0",
+  "description": "Charge for an Express API with x402, settled and reconciled through BillMyAgent",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "x402",
+    "express",
+    "payments",
+    "usdc",
+    "facilitator"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "x402": "1.2.0",
+    "x402-express": "1.2.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3"
+  },
+  "overrides": {
+    "axios": "^1.18.0",
+    "ws": "^8.21.0",
+    "uuid@<11.1.1": "^11.1.1",
+    "qs": "^6.16.0"
+  }
+}