@profullstack/x402-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @profullstack/x402-client
+
+Pay an [x402](https://x402.org) `402 Payment Required` from Node with a local key. Sign the EIP-3009 authorization, retry with the proof, keep the pass.
+
+A crawler, an agent, or a script that meets a paid site needs three things: to read the offer, to sign it with a key it holds, and to remember what it bought so the next thousand requests are free. That is the whole package: a `fetch` that does all three, a CLI for shells, and the header that lets Lightpanda, Puppeteer or curl through a site sold by [@profullstack/x402-gateway](https://github.com/profullstack/x402-gateway) or any other x402 v2 server.
+
+```
+npm install @profullstack/x402-client
+```
+
+Two dependencies, `@noble/curves` and `@noble/hashes`, for one hash function and one signature. No ethers, no viem, no RPC: the payer never sends a transaction and never needs ETH. The facilitator broadcasts the authorization and pays the gas; the wallet holds USDC and signs.
+
+## Fetch
+
+```js
+import { createClient } from '@profullstack/x402-client';
+
+const client = createClient({ key: process.env.X402_PRIVATE_KEY });
+
+const res = await client.fetch('https://rssamplifier.com/some/page');
+// 402 → paid → the page. The pass is filed by origin, so:
+const again = await client.fetch('https://rssamplifier.com/another/page');
+// presents the pass, pays nothing.
+```
+
+`fetch` behaves like the global one until it sees a 402 carrying an x402 offer. Then it picks the first option it can sign, signs an EIP-3009 `TransferWithAuthorization` for exactly the offered amount to exactly the offered address, and asks again with the proof in `X-PAYMENT` and `PAYMENT-SIGNATURE`. A gateway answers with a receipt naming a pass, which is filed and presented on every later request to that origin; a plain x402 resource answers with the resource, which is returned as it came.
+
+It pays once per request and never guesses: a second 402 after a proof means the payment was refused, and that is thrown as an `X402Error` with `code: 'rejected'` and the server's reason, not retried with a fresh signature.
+
+## Pay, explicitly
+
+```js
+const result = await client.pay('https://rssamplifier.com/crawl');
+result.payer;           // 0x… the address that signed
+result.amountUsd;       // 1
+result.network;         // 'eip155:8453'
+result.receipt.pass;    // 'cp_…'   the day pass
+result.receipt.header;  // 'x-crawl-pass'  where to put it
+result.receipt.expires; // ISO timestamp
+```
+
+`pay` asks the URL for its offer (as JSON), signs, and files whatever pass comes back. Give it `{ offer }` to skip the first request when you already hold one.
+
+## Options
+
+```js
+createClient({
+  key,                    // 32-byte secp256k1 private key, hex. Or `wallet`.
+  maxUsd: 5,              // refuse any single payment above this. Default 5.
+  networks: ['eip155:8453'], // only pay on these chains, e.g. the one you funded
+  store: 'file',          // file passes in ~/.config/x402-client/passes.json; default memory
+  userAgent: 'MyBot/1.0 (+https://…)',
+  validForSeconds,        // authorization lifetime; defaults to the offer's maxTimeoutSeconds
+  fetch,                  // your own fetch, for proxies and tests
+});
+```
+
+The ceiling is the one setting to think about. A client that holds a key and pays whatever it is asked is a client a hostile server can drain by asking. A day of crawling on a gateway costs a dollar; five is room for a dearer site and not for a mistake.
+
+`networks` matters because the server's `accepts` is in its order of preference, and the first entry may be a chain your wallet has no USDC on. A signed authorization on an empty wallet verifies and then fails to settle, and the server answers 402 as if you had never paid.
+
+## The CLI
+
+```
+npm install -g @profullstack/x402-client
+export X402_PRIVATE_KEY=0x…
+
+x402 address                       # fund this
+x402 pay https://site/crawl        # receipt as JSON
+x402 pass https://site/crawl       # the pass, buying one if none is on file
+x402 fetch https://site/page       # the page, paying if it asks
+x402 passes                        # what is on file
+```
+
+The key is read from the environment or `--key-file`, never from an argument. Passes are filed in `$XDG_CONFIG_HOME/x402-client/passes.json` with mode 0600, so one invocation buys and the rest present:
+
+```
+curl -H "x-crawl-pass: $(x402 pass https://site/crawl)" https://site/page
+lightpanda fetch --http-header "x-crawl-pass: $(x402 pass https://site/crawl)" https://site/page
+```
+
+## Lightpanda and Puppeteer
+
+Lightpanda has no plugin system, and does not need one: a gateway sells time, not pages, so the browser only has to carry the header a payment bought. The shell line above is the whole integration. For a script, [`examples/lightpanda.mjs`](examples/lightpanda.mjs) connects Puppeteer to `lightpanda serve`, presents the filed pass, and on a 402 pays from Node and reloads. The browser never holds the key. Nothing in it is Lightpanda-specific; it works against Chrome.
+
+## What is signed
+
+x402's `exact` scheme on EVM is EIP-3009: the payer signs a `TransferWithAuthorization` under the **token's** EIP-712 domain, and whoever holds the signature can move exactly that amount to exactly that address, once, before `validBefore`. The signature is the payment. The client:
+
+- takes the domain from the offer's `extra: { name, version }`, falling back to a table of USDC deployments read from the contracts, and refuses to sign a token whose domain it does not know, because a guessed domain recovers to the wrong address and fails with no diagnostic
+- sets `validAfter` to 0 and bounds `validBefore` by the offer's own `maxTimeoutSeconds`, so no spendable authorization outlives the server's promise to settle
+- uses a fresh random 32-byte nonce per payment
+- emits `v` as 27/28, which is what `ecrecover` in `transferWithAuthorization` expects
+
+The signer is a port of the one in CoinPay Wallet, which was checked byte for byte against ethers; the test suite holds this port to a digest and signature produced by that original.
+
+## Errors
+
+`X402Error` carries a `code`:
+
+| code | meaning |
+| --- | --- |
+| `no-key` | the client has no key and was asked to pay |
+| `no-offer` | the URL answered 402 with no x402 in it, or did not answer 402 |
+| `no-option` | nothing in `accepts` is `exact` on an EVM chain in `networks` |
+| `too-expensive` | over `maxUsd`, or a token this client cannot price |
+| `rejected` | the server refused the proof; `body` has its reason |
+
+## License
+
+MIT

package/bin/x402.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * x402 from a shell.
+ *
+ *   x402 pay <url>          pay the offer at a URL, print the receipt as JSON
+ *   x402 pass <url>         print the pass for a URL's site, buying one if needed
+ *   x402 fetch <url>        fetch a URL, paying if it asks, print the body
+ *   x402 address            the address the key controls, to fund it
+ *   x402 passes             the passes on file
+ *
+ * The key comes from `X402_PRIVATE_KEY` or `--key-file <path>`, never from an
+ * argument: a key on the command line is in every process list and shell
+ * history on the box. Passes are filed in `$XDG_CONFIG_HOME/x402-client/
+ * passes.json` so a second invocation, or curl, or Lightpanda, reuses what
+ * the first one bought:
+ *
+ *   lightpanda fetch --http-header "x-crawl-pass: $(x402 pass https://site/crawl)" https://site/page
+ */
+
+import { readFileSync } from 'node:fs';
+
+import { createClient, X402Error } from '../src/client.js';
+import { fileStore, originOf } from '../src/passes.js';
+
+const HELP = `usage: x402 <command> [options]
+
+commands
+  pay <url>        pay the offer at <url> and print the receipt (JSON)
+  pass <url>       print the pass for <url>'s site, buying one if none is on file
+  fetch <url>      fetch <url>, paying if it asks, and print the body
+  address          print the address the key controls
+  passes           list the passes on file
+
+options
+  --key-file <path>    read the private key from a file (or set X402_PRIVATE_KEY)
+  --max-usd <n>        refuse any single payment above this (default 5)
+  --network <caip2>    only pay on this network, e.g. eip155:8453; repeatable
+  --store <path>       where passes are filed (default ~/.config/x402-client/passes.json)
+  -H, --header <k: v>  extra request header; repeatable
+  --json               print machine-readable output for pass and fetch
+  -h, --help           this
+`;
+
+function parse(argv) {
+  const opts = { headers: [], networks: [], json: false };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) fail(`${a} needs a value`);
+      return argv[++i];
+    };
+    if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--key-file') opts.keyFile = next();
+    else if (a === '--max-usd') opts.maxUsd = Number(next());
+    else if (a === '--network') opts.networks.push(next());
+    else if (a === '--store') opts.store = next();
+    else if (a === '-H' || a === '--header') opts.headers.push(next());
+    else if (a.startsWith('-')) fail(`unknown option ${a}`);
+    else rest.push(a);
+  }
+  return { opts, command: rest[0], args: rest.slice(1) };
+}
+
+function fail(message, code = 2) {
+  process.stderr.write(`x402: ${message}\n`);
+  process.exit(code);
+}
+
+function keyFrom(opts) {
+  if (opts.keyFile) return readFileSync(opts.keyFile, 'utf8').trim();
+  return process.env.X402_PRIVATE_KEY?.trim() || null;
+}
+
+function headersFrom(list) {
+  const headers = {};
+  for (const line of list) {
+    const at = line.indexOf(':');
+    if (at < 1) fail(`header must be "Name: value", got ${JSON.stringify(line)}`);
+    headers[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+  }
+  return headers;
+}
+
+async function main() {
+  const { opts, command, args } = parse(process.argv.slice(2));
+  if (opts.help || !command) {
+    process.stdout.write(HELP);
+    process.exit(opts.help ? 0 : 2);
+  }
+
+  const store = fileStore(opts.store);
+  const key = keyFrom(opts);
+  const needsKey = command === 'pay' || command === 'address';
+  if (needsKey && !key) fail('no key: set X402_PRIVATE_KEY or pass --key-file <path>');
+
+  const client = createClient({
+    key: key ?? undefined,
+    store,
+    maxUsd: Number.isFinite(opts.maxUsd) ? opts.maxUsd : undefined,
+    networks: opts.networks.length ? opts.networks : undefined,
+  });
+
+  const url = args[0];
+  const needsUrl = command === 'pay' || command === 'pass' || command === 'fetch';
+  if (needsUrl && !url) fail(`${command} needs a URL`);
+
+  if (command === 'address') {
+    process.stdout.write(`${client.address}\n`);
+    return;
+  }
+
+  if (command === 'passes') {
+    const all = store.all();
+    if (opts.json) process.stdout.write(`${JSON.stringify(all, null, 2)}\n`);
+    else {
+      const rows = Object.entries(all);
+      if (rows.length === 0) process.stdout.write(`no passes on file (${store.path})\n`);
+      for (const [origin, pass] of rows) {
+        process.stdout.write(`${origin}\t${pass.header}\t${pass.expires ?? 'no expiry'}\t${pass.token.slice(0, 24)}…\n`);
+      }
+    }
+    return;
+  }
+
+  if (command === 'pay') {
+    const result = await client.pay(url, { init: { headers: headersFrom(opts.headers) } });
+    process.stdout.write(`${JSON.stringify(receiptOf(result), null, 2)}\n`);
+    return;
+  }
+
+  if (command === 'pass') {
+    let pass = client.passFor(url);
+    if (!pass) {
+      if (!key) fail(`no pass on file for ${originOf(url)} and no key to buy one: set X402_PRIVATE_KEY`);
+      const result = await client.pay(url, { init: { headers: headersFrom(opts.headers) } });
+      if (!result.receipt.pass) fail(`${url} took the payment but issued no pass`, 1);
+      pass = client.passFor(url);
+    }
+    if (opts.json) process.stdout.write(`${JSON.stringify(pass, null, 2)}\n`);
+    else process.stdout.write(`${pass.token}\n`);
+    return;
+  }
+
+  if (command === 'fetch') {
+    const res = await client.fetch(url, { headers: headersFrom(opts.headers) });
+    const text = await res.text();
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ status: res.status, headers: Object.fromEntries(res.headers), body: text }, null, 2)}\n`,
+      );
+    } else {
+      process.stdout.write(text);
+      if (!text.endsWith('\n')) process.stdout.write('\n');
+    }
+    if (res.status >= 400) process.exit(1);
+    return;
+  }
+
+  fail(`unknown command ${command}\n\n${HELP}`);
+}
+
+function receiptOf(result) {
+  return {
+    status: result.status,
+    payer: result.payer,
+    payTo: result.payTo,
+    network: result.network,
+    amount: result.amount,
+    amountUsd: result.amountUsd,
+    nonce: result.nonce,
+    pass: result.receipt.pass,
+    header: result.receipt.header,
+    expires: result.receipt.expires,
+    settlement: result.receipt.settlement,
+    body: result.body,
+  };
+}
+
+main().catch((err) => {
+  if (err instanceof X402Error) {
+    process.stderr.write(`x402: ${err.message}\n`);
+    if (err.body && typeof err.body === 'object') process.stderr.write(`${JSON.stringify(err.body, null, 2)}\n`);
+    process.exit(1);
+  }
+  process.stderr.write(`x402: ${err?.stack ?? err}\n`);
+  process.exit(1);
+});

package/index.d.ts

@@ -0,0 +1,197 @@
+export interface TypedDataField {
+  name: string;
+  type: string;
+}
+export type TypedDataTypes = Record<string, TypedDataField[]>;
+export interface TypedDataDomain {
+  name?: string;
+  version?: string;
+  chainId?: number | bigint | string;
+  verifyingContract?: string;
+  salt?: string;
+}
+
+export interface Wallet {
+  /** EIP-55 checksummed address. */
+  readonly address: string;
+  signTypedData(domain: TypedDataDomain, types: TypedDataTypes, primaryType: string, message: Record<string, unknown>): string;
+}
+
+/** One option in a 402's `accepts`. */
+export interface AcceptEntry {
+  scheme?: string;
+  network: string;
+  amount?: string;
+  maxAmountRequired?: string;
+  asset?: string;
+  payTo?: string;
+  resource?: string;
+  description?: string;
+  mimeType?: string;
+  maxTimeoutSeconds?: number;
+  extra?: { name?: string; version?: string; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+export interface Offer {
+  x402Version?: number;
+  accepts: AcceptEntry[];
+  [k: string]: unknown;
+}
+
+export interface Authorization {
+  from: string;
+  to: string;
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: string;
+}
+
+export interface Payment {
+  x402Version: number;
+  scheme: string;
+  network: string;
+  payload: { signature: string; authorization: Authorization };
+}
+
+export interface StoredPass {
+  token: string;
+  header: string;
+  expires: string | null;
+  boughtAt: string;
+  url: string | null;
+}
+
+export interface PassStore {
+  get(origin: string): StoredPass | null;
+  set(origin: string, pass: StoredPass): void;
+  delete(origin: string): void;
+  all(): Record<string, StoredPass>;
+  path?: string;
+}
+
+export interface Receipt {
+  pass: string | null;
+  header: string;
+  expires: string | null;
+  settlement: object | null;
+}
+
+export interface PayResult {
+  status: number;
+  body: unknown;
+  receipt: Receipt;
+  payer: string;
+  network: string;
+  amount: string;
+  amountUsd: number | null;
+  payTo: string | undefined;
+  nonce: string;
+  payment: Payment;
+}
+
+export interface ClientOptions {
+  /** 32-byte secp256k1 private key, hex. */
+  key?: string | Uint8Array;
+  /** A wallet, instead of a key. */
+  wallet?: Wallet;
+  /** Only pay on these CAIP-2 networks, in the server's order of preference. */
+  networks?: string[];
+  /** Refuse any single payment above this many dollars. Default 5. */
+  maxUsd?: number;
+  /** How long a signed authorization stays valid; defaults to the offer's maxTimeoutSeconds, else 600. */
+  validForSeconds?: number;
+  /** A User-Agent to send when the caller sets none. */
+  userAgent?: string;
+  /** Where passes are filed: a store, or 'file' for the default file. Default memory. */
+  store?: PassStore | 'file';
+  /** A fetch to use instead of the global one. */
+  fetch?: typeof fetch;
+}
+
+export interface X402Client {
+  /** The paying address, or null for a client without a key. */
+  readonly address: string | null;
+  readonly store: PassStore;
+  /** fetch that presents a filed pass and pays a 402 once. */
+  fetch(input: string | URL | Request, init?: RequestInit, options?: { pay?: boolean }): Promise<Response>;
+  /** Pay for a URL (asking it for the offer first unless one is given) and file any pass. */
+  pay(url: string | URL | Request, options?: { offer?: Offer; init?: RequestInit }): Promise<PayResult>;
+  /** The live pass filed for a URL's origin. */
+  passFor(url: string | URL): StoredPass | null;
+}
+
+export type X402ErrorCode = 'no-key' | 'no-offer' | 'no-option' | 'too-expensive' | 'rejected';
+
+export class X402Error extends Error {
+  code: X402ErrorCode | string;
+  status: number | null;
+  body: unknown;
+  offer: Offer | null;
+  url: string | null;
+}
+
+export const DEFAULT_MAX_USD: number;
+export const X402_VERSION: number;
+export const KNOWN_TOKEN_DOMAINS: Record<string, { name: string; version: string; decimals: number }>;
+export const TRANSFER_WITH_AUTHORIZATION_TYPES: TypedDataTypes;
+
+export function createClient(options?: ClientOptions): X402Client;
+export function walletFromKey(privateKey: string | Uint8Array): Wallet;
+export function randomWallet(): { wallet: Wallet; privateKey: string };
+
+export function memoryStore(): PassStore;
+export function fileStore(path?: string): PassStore;
+export function defaultPassPath(): string;
+export function originOf(url: string | URL): string;
+export function isLive(pass: StoredPass | null | undefined, now?: number): boolean;
+
+export function evmChainId(network: string): number | null;
+export function readOffer(response: Response): Promise<{ offer: Offer | null; body: unknown }>;
+export function isOffer(value: unknown): value is Offer;
+export function selectAccept(accepts: AcceptEntry[], options?: { networks?: string[] }): AcceptEntry | null;
+export function domainFor(entry: AcceptEntry): { name: string; version: string; chainId: number; verifyingContract: string };
+export function requiredAmount(entry: AcceptEntry): string;
+export function amountUsd(entry: AcceptEntry): number | null;
+export function randomNonce(): string;
+export function buildAuthorization(args: {
+  from: string;
+  to: string;
+  value: string | number | bigint;
+  validForSeconds?: number;
+  nonce?: string;
+  now?: number;
+}): Authorization;
+export function signPayment(
+  entry: AcceptEntry,
+  wallet: Wallet,
+  options?: { validForSeconds?: number; nonce?: string; now?: number },
+): { payment: Payment; header: string; authorization: Authorization; domain: TypedDataDomain };
+export function encodePaymentHeader(payment: Payment): string;
+export function decodePaymentHeader(header: string | null | undefined): Payment | null;
+export function readReceipt(response: Response, body: unknown): Receipt;
+
+export function eip712Digest(domain: TypedDataDomain, types: TypedDataTypes, primaryType: string, message: Record<string, unknown>): Uint8Array;
+export function signTypedData(
+  domain: TypedDataDomain,
+  types: TypedDataTypes,
+  primaryType: string,
+  message: Record<string, unknown>,
+  privateKey: Uint8Array,
+): string;
+export function recoverTypedDataSigner(
+  domain: TypedDataDomain,
+  types: TypedDataTypes,
+  primaryType: string,
+  message: Record<string, unknown>,
+  signature: string,
+): string;
+export function addressOfPublicKey(publicKey: Uint8Array): string;
+export function checksumAddress(address: string): string;
+export function hashStruct(primaryType: string, types: TypedDataTypes, data: Record<string, unknown>): Uint8Array;
+export function hashDomain(domain: TypedDataDomain): Uint8Array;
+export function encodeType(primaryType: string, types: TypedDataTypes): string;
+export function typeHash(primaryType: string, types: TypedDataTypes): Uint8Array;
+export function hexToBytes(hex: string): Uint8Array;
+export function bytesToHex(bytes: Uint8Array): string;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@profullstack/x402-client",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pay an x402 402 from Node with a local key: sign the EIP-3009 authorization, retry with the proof, keep the pass. A fetch, a CLI, and the header that lets Lightpanda, Puppeteer or curl through a paid site.",
+  "keywords": [
+    "x402",
+    "402",
+    "payment-required",
+    "eip-3009",
+    "eip-712",
+    "usdc",
+    "coinpay",
+    "crawler",
+    "lightpanda",
+    "puppeteer",
+    "headless",
+    "agent",
+    "micropayment"
+  ],
+  "repository": { "type": "git", "url": "git+https://github.com/profullstack/x402-client.git" },
+  "homepage": "https://github.com/profullstack/x402-client#readme",
+  "bugs": { "url": "https://github.com/profullstack/x402-client/issues" },
+  "license": "MIT",
+  "author": "Profullstack, LLC",
+  "bin": { "x402": "./bin/x402.js" },
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./src/index.js" }
+  },
+  "types": "./index.d.ts",
+  "files": ["src", "bin", "index.d.ts", "README.md", "LICENSE"],
+  "engines": { "node": ">=20.19" },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0"
+  }
+}