@tollstile/x402 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paradigm AI Inc.
+
+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,146 @@
+# @tollstile/x402
+
+The [x402](https://github.com/x402-foundation/x402) V2 rail for Tollstile. Agents pay per request in USDC (or another EVM token) with a signed authorization; Tollstile verifies it through a facilitator before your handler runs and settles it after the handler succeeded.
+
+- **Schemes:** `exact` (EIP-3009 `transferWithAuthorization`) for fixed prices, `upto` (Permit2) for `upTo()` prices.
+- **Transports:** HTTP (`PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE`, standard base64 JSON) and MCP (`_meta["x402/payment"]`, receipt in `_meta["x402/payment-response"]`, payment-required as an `isError` tool result).
+- **Reconciliation:** on-chain, through your JSON-RPC endpoint. x402 facilitators have no status endpoint and `/settle` is not idempotent.
+
+## Install
+
+```bash
+npm install tollstile @tollstile/x402
+```
+
+## Example
+
+```ts
+import { Hono } from 'hono';
+import { createTollstile, memoryLedger, upTo } from 'tollstile';
+import { tollstile } from '@tollstile/hono';
+import { x402 } from '@tollstile/x402';
+
+const toll = createTollstile({
+  rails: [
+    x402({
+      network: 'eip155:84532', // Base Sepolia
+      payTo: '0xYourAddress',
+      denomination: 'USD', // 1 USDC = 1 USD, stated explicitly
+      rpcUrl: 'https://sepolia.base.org',
+      upto: { facilitatorAddress: '0xd407e409E34E0b9afb99EcCeb609bDbcD5e7f1bf' }, // from GET /supported
+    }),
+  ],
+  ledger: memoryLedger(),
+  secret: process.env.TOLLSTILE_SECRET, // 32+ random characters
+});
+
+const app = new Hono();
+app.get('/weather', tollstile(toll.price('$0.01')), (c) => c.json({ sunny: true }));
+app.post('/generate', tollstile(toll.price(upTo('$0.10'))), async (c) => {
+  await c.get('payment').fulfill({ amount: '$0.03' }); // settles 0.03 USDC of the 0.10 authorized
+  return c.json({ text: '…' });
+});
+
+setInterval(() => void toll.reconcile(), 60_000);
+```
+
+Start with `testRail()` from `tollstile` for local development; switching to `x402()` does not change handlers.
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `network` | — | CAIP-2 EVM network. Built-in assets: `eip155:8453` (Base, USDC "USD Coin" v2) and `eip155:84532` (Base Sepolia, USDC "USDC" v2). |
+| `payTo` | — | Your receiving address. Every payment is checked against it. |
+| `denomination` | — | Conversion at par, e.g. `"USD"` for USDC. Required unless `rate` is set; the built-in USDC only accepts `"USD"`. |
+| `rate` | — | `(price: Money) => Promise<bigint>`: atomic asset units for a price, for assets not at par. The quote fixes the result for the payer. |
+| `asset` | built-in USDC | `{ code, address, decimals, name, version }` with the token's EIP-712 domain. Required on other networks; decimals 6–18. |
+| `facilitator` | x402.org on Base Sepolia only | `{ url, headers?: () => Promise<Record<string, string>> }`. `headers` runs per request (e.g. a CDP JWT). **Required on mainnet and every other network**; the testnet facilitator is never used silently. |
+| `rpcUrl` | — | JSON-RPC endpoint for `network`, used only by reconciliation. Must support the `finalized` block tag and `eth_getLogs`. |
+| `upto` | disabled | `{ facilitatorAddress }` enables `upTo()` prices. Use the address your facilitator lists for `upto` in `GET /supported`; payers bind their Permit2 signature to it. |
+| `maxTimeoutSeconds` | `60` | Advertised to payers, who sign authorizations valid for about this long. **The handler and settlement must both finish before it runs out** (facilitators also keep a few seconds of margin), or settlement is rejected after the service was delivered. Raise it for slow handlers. |
+| `fetch` | global `fetch` | Injected for tests and custom transports. |
+
+## Capabilities
+
+| Capability | Value | Why |
+|---|---|---|
+| `flows` | `['authorization']` | verify → handler → settle. `exact` cannot be refunded or voided, so settling upfront would charge for work that failed. |
+| `authorization` | `single` | One signed authorization pays for one request. After a released charge (handler failed, nothing settled) the same payment can be retried. |
+| `variableAmount` | `true` with `upto` | Permit2 `upto` authorizes a maximum and settles the fulfilled amount. |
+| `quotes` | `true` | The quote token travels in `accepts[].extra.tollstileQuote`. x402 V2 clients must echo every advertised `extra` field, so it comes back in `accepted`. |
+| `refund` / `partialRefund` | `false` | Neither scheme has a refund; `refund()` throws `UNREACHABLE`. |
+| `lookup` | `true` | On-chain, see below. |
+
+`livemode` is `true`, including on testnets.
+
+### How verification works
+
+1. Read `PAYMENT-SIGNATURE` (HTTP) or `_meta["x402/payment"]` (MCP). Only `x402Version: 2` is accepted.
+2. If `accepted.extra.tollstileQuote` is present, open the quote and derive the requirements from its x402 offer; otherwise use the route's fixed price (dynamic routes need the quote).
+3. `accepted` must equal those requirements (every field except `extra` identical; `extra` must contain everything advertised, as in the reference `paymentRequirementsMatchAccepted`). The signed authorization must name `payTo`, the exact amount (or the `upto` maximum), the asset, the upto proxy as spender, and the configured facilitator.
+4. Call the facilitator `/verify` with **this server's** requirements, never the client's.
+5. `payer` is the signer's address in lowercase hex. The proof id is `network:asset:payer:nonce`, so a replayed payment maps to the same authorization. `limit` is the authorized value converted back to money; `expiresAt` is `validBefore` (or the Permit2 deadline).
+
+Denials use core's error codes (SPEC §12). Every rejection by this rail is `402` with `error.code: "proof_invalid"` and the rail's reason in `error.detail` (e.g. `accepted_mismatch`, `recipient_mismatch`, or the facilitator's `invalidReason`, sanitized to `[a-z0-9_]`, whether it came as HTTP 200 or a non-2xx JSON body); a forged or expired quote is `quote_invalid`. Clients branch on `code`, never on `detail`. An unreachable or timed-out facilitator, a non-JSON answer, or `unexpected_verify_error` is `503 payment_unavailable` and the handler does not run.
+
+**Retries and idempotency.** The 402 advertises the x402 `payment-identifier` extension. A client that sends `extensions["payment-identifier"].info.id` (16–128 characters of `[A-Za-z0-9_-]`) gets it used as the idempotency key; an `Idempotency-Key` header (or MCP `_meta["tollstile/idempotency-key"]`) takes precedence. A malformed id is `proof_invalid` / `payment_identifier_invalid`. With a key, a retry while the first request runs is `409 request_in_progress`; without one, a second presentation of the same signature is `409 proof_already_used`. After the payment **settled**, the facilitator rejects the used nonce, but the rail still reports which authorization the payment identifies, so core answers `409 already_paid` (same `Idempotency-Key` or payment identifier) or `409 proof_already_used` instead of asking the client to pay again. The same holds when the quote in a retried payment has expired. A payload whose signature the facilitator rejects proves no identity and is `402 proof_invalid`. A retry after the handler failed (charge released) runs again with the same signature.
+
+### How settlement works
+
+`/settle` is called with the stored payload and requirements; for `upto`, `amount` is the fulfilled amount at the quoted ratio, rounded down. `success: false` is a rejection (`failed`), except `settlement_pending` and `unexpected_settle_error`, which — like timeouts, transport failures, and non-JSON answers — are `PROVIDER_TIMEOUT`: core records `unknown` and reconciliation asks the chain. Tollstile never calls `/settle` twice on a hunch.
+
+### How lookup works
+
+All reads happen at the `finalized` block.
+
+- **exact:** `authorizationState(payer, nonce)` on the token. If used, find the token's `AuthorizationUsed(payer, nonce)` log and require a `Transfer(payer, payTo, value)` in the same successful transaction → `settled` with that transaction hash. An `AuthorizationCanceled` log → `none`.
+- **upto:** Permit2 `nonceBitmap(payer, nonce >> 8)`. If the bit is set, find `Transfer(payer, payTo)` logs of the asset and accept one only if its transaction called the upto proxy (`settle` or `settleWithPermit`) with this nonce, owner, and token; the settled amount comes from the log. An `UnorderedNonceInvalidation` covering the nonce → `none`.
+- **Unused nonce:** `none` only once the finalized block is past `validBefore` (or the deadline), when no later block can include it. Before that, lookup throws `PROVIDER_TIMEOUT` and the charge stays `unknown` until the next run.
+- **Used nonce with no recognizable evidence** (e.g. a facilitator that settles through a batching contract): `PROVIDER_TIMEOUT` with a message to investigate. Tollstile does not guess.
+
+Logs are searched between the charge's creation time (minus 10 minutes of clock-skew margin) and the signature's deadline. Block timestamps strictly increase, which bounds that block range without assuming a block time.
+
+Selectors and topics are precomputed constants in `src/abi.ts` (no keccak dependency); each is documented with its signature.
+
+### Stored data
+
+The authorization's `data` holds the payer's signed payload, because settlement may run in another process after a crash. It never appears in errors, events, or receipts. The rail implements `redact`: once a charge is final, core replaces `paymentPayload` and `paymentRequirements` with `null`, keeping the scheme, network, asset, `payTo`, payer, nonce, deadline, and amounts that `lookup` needs. While a charge is `unknown` the payload stays, so reconciliation can still settle it. A `released` charge (the handler failed before anything settled) is not redacted, so the same payment can be retried.
+
+## Verification status
+
+**Tested only against fakes and the reference library.**
+
+- `test/x402.test.ts` drives real flows through `createTollstile` with a fake facilitator and a fake JSON-RPC node sharing one simulated chain (injected `fetch`): 402 → pay with the echoed quote → 200 for `exact` and `upto` (fulfilled amount); dynamic prices; tampered `accepted` amount, recipient, network, asset, and timeout; signatures to another recipient, amount, spender, or facilitator; tampered and expired quotes; facilitator unreachable, hanging (abort), and `unexpected_verify_error` → 503; replay after settlement (`409 proof_already_used`, or `409 already_paid` with the same `Idempotency-Key` even after the quote expired) and concurrent replay (`409 proof_already_used`); a facilitator signature rejection stays `402 proof_invalid`; `payment-identifier` as idempotency key (`409 request_in_progress` in flight, `409 already_paid` after settlement, malformed id rejected); canonical lowercase payer; retry after a released charge; rejected settlement as 200 and non-2xx (fresh 402 `settlement_rejected` after the handler); `settlement_pending` → `unknown` → reconciled to `settled` from chain evidence (exact and upto) without a second `/settle`; unmined authorization kept `unknown` until expired, then `failed`; payer cancellation (EIP-3009 and Permit2 invalidation, with a decoy transfer) → nothing charged; RPC down → stays `unknown`; crash after fulfillment → settled by reconciliation; MCP challenge and receipt; redaction (payload kept until final and while `unknown`, kept after a release and dropped once the retry settles, dropped after settle, rejection, and reconciliation; lookup still works on redacted data); configuration errors.
+- `test/rail-conformance.test.ts` runs core's `railConformance()` kit against the same fakes for the `exact` scheme, with lost settle responses, settle failures before any effect, and tampered proofs: all 9 cases pass, none skipped. The kit prices routes with a fixed string, so `upto` is not exercised by it (it is covered in `x402.test.ts`).
+- `test/conformance.test.ts` round-trips headers through `@x402/core` 2.25.0 (`decodePaymentRequiredHeader`, `encodePaymentSignatureHeader`, `decodePaymentResponseHeader`, V2 schema guards) and checks that the reference `x402ResourceServer.findMatchingRequirements` accepts what this rail advertises.
+- ABI selectors and event topics were computed with keccak-256 and cross-checked against known selectors (`balanceOf`, `transferWithAuthorization`, `Transfer`); calldata layouts follow `x402UptoPermit2Proxy.sol` at x402-foundation/x402 `3a6605e`.
+
+**Live verification status.** The `exact` flow has been verified on Base Sepolia with x402.org, including a successful USDC transfer, replay rejection, handler failure followed by retry, and persistence across a process restart with the SQLite ledger. `upto`, reconciliation after an ambiguous settlement, and production providers still require separate verification.
+
+### Verify live on Base Sepolia with the x402.org facilitator
+
+1. **Wallets.** Create two test wallets: a receiver (`payTo`) and a payer. Fund the payer with Base Sepolia USDC from https://faucet.circle.com. For `exact`, the payer needs no ETH (the facilitator pays gas). For `upto`, the payer must approve Permit2 (`0x000000000022D473030F116dDEE9F6B43aC78BA3`) for USDC once, which needs a little Base Sepolia ETH.
+2. **Facilitator address.** `curl https://x402.org/facilitator/supported` and copy `extra.facilitatorAddress` of the `upto` / `eip155:84532` entry (it was `0xd407e409E34E0b9afb99EcCeb609bDbcD5e7f1bf` on 2026-09-15).
+3. **Server.** Run the example above with `network: 'eip155:84532'`, your `payTo`, `denomination: 'USD'`, `rpcUrl: 'https://sepolia.base.org'` (or a provider URL), `upto: { facilitatorAddress }`, a Postgres or memory ledger, and `onEvent: console.log`.
+4. **Unpaid request.** `curl -i localhost:3000/weather` → `402`, `cache-control: no-store`, and a `PAYMENT-REQUIRED` header; `echo <header> | base64 -d` shows `scheme: "exact"`, `amount: "10000"`, and `extra.tollstileQuote`.
+5. **Paid request with the reference client.**
+   ```ts
+   import { x402Client, wrapFetchWithPayment, decodePaymentResponseHeader } from '@x402/fetch';
+   import { ExactEvmScheme } from '@x402/evm/exact/client';
+   import { UptoEvmScheme } from '@x402/evm/upto/client';
+   import { privateKeyToAccount } from 'viem/accounts';
+
+   const signer = privateKeyToAccount(process.env.PAYER_KEY as `0x${string}`);
+   const client = new x402Client().register('eip155:84532', new ExactEvmScheme(signer)).register('eip155:84532', new UptoEvmScheme(signer));
+   const pay = wrapFetchWithPayment(fetch, client);
+
+   const weather = await pay('http://localhost:3000/weather');
+   console.log(weather.status, decodePaymentResponseHeader(weather.headers.get('payment-response') ?? ''));
+   const generate = await pay('http://localhost:3000/generate', { method: 'POST' });
+   console.log(generate.status, decodePaymentResponseHeader(generate.headers.get('payment-response') ?? ''));
+   ```
+   Expect `200` and a transaction hash. On https://sepolia.basescan.org, `/weather` shows a 0.01 USDC transfer to `payTo` with an `AuthorizationUsed` event; `/generate` shows 0.03 USDC through the upto proxy `0x4020…0002`. The ledger shows `settled/completed` charges.
+6. **Replay.** Log the `PAYMENT-SIGNATURE` header the client sent (wrap its `fetch`) and send it again with `curl -H` → `409` with `error.code: "proof_already_used"` (or `already_paid` when you also resend the same `Idempotency-Key`), no second transfer.
+7. **Handler failure.** Make the handler return 500 once → the charge is `released/failed`, no transfer; resend the same header within `maxTimeoutSeconds` → `200` and one transfer.
+8. **Reconciliation.** Point `facilitator.url` at a small proxy that forwards `/verify` normally but forwards `/settle` to x402.org and then answers `504` → the charge is `unknown`. Wait for the finalized block to pass the settlement (a few minutes on Base Sepolia), run `toll.reconcile({ olderThanMs: 0 })` → `settled` with the on-chain hash and no second `/settle`. Repeat with a proxy that drops `/settle` without forwarding it, wait until finality passes `validBefore`, reconcile → `failed`, no transfer.

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { Money, JsonObject, Rail } from 'tollstile';
+
+/** A token that settles x402 payments on an EVM network. */
+type X402Asset = {
+    /** Asset code recorded on offers, e.g. `"USDC"`. */
+    readonly code: string;
+    readonly address: string;
+    readonly decimals: number;
+    /** EIP-712 domain name of the token contract, advertised as `extra.name`. */
+    readonly name: string;
+    /** EIP-712 domain version of the token contract, advertised as `extra.version`. */
+    readonly version: string;
+};
+
+type Fetch = typeof fetch;
+
+type X402FacilitatorOptions = {
+    /** Base URL; `/verify` and `/settle` are appended. */
+    readonly url: string;
+    /** Headers for each request, e.g. a freshly signed CDP JWT. Called once per request. */
+    readonly headers?: () => Promise<Record<string, string>>;
+};
+type X402Options = {
+    /** CAIP-2 network, e.g. `"eip155:84532"` (Base Sepolia) or `"eip155:8453"` (Base). */
+    readonly network: string;
+    /** Your address. Payments are signed to it and checked against it. */
+    readonly payTo: string;
+    /**
+     * The currency the asset is pegged to, for conversion at par: `"USD"` for USDC. Set exactly one
+     * of `denomination` and `rate`; Tollstile never assumes a conversion.
+     */
+    readonly denomination?: string;
+    /** Converts a price to atomic units of the asset when it is not at par. The quote fixes the result. */
+    readonly rate?: (price: Money) => Promise<bigint>;
+    /** Defaults to USDC on Base and Base Sepolia. Required on other networks. */
+    readonly asset?: X402Asset;
+    /**
+     * The facilitator that verifies and settles. Defaults to https://x402.org/facilitator on Base
+     * Sepolia only; required everywhere else.
+     */
+    readonly facilitator?: X402FacilitatorOptions;
+    /**
+     * JSON-RPC endpoint for `network`. Facilitators have no status endpoint and `/settle` is not
+     * idempotent, so reconciliation reads authorization nonces and transfer logs from the chain.
+     */
+    readonly rpcUrl: string;
+    /**
+     * Enables `upTo()` prices with the `upto` scheme (Permit2). `facilitatorAddress` is the address
+     * your facilitator lists for `upto` in `GET /supported`; payers bind their signature to it.
+     */
+    readonly upto?: {
+        readonly facilitatorAddress: string;
+    };
+    /**
+     * How long a payer's signature stays valid. Defaults to 60. The handler and settlement must both
+     * finish before it runs out, or settlement is rejected after the service was delivered.
+     */
+    readonly maxTimeoutSeconds?: number;
+    readonly fetch?: Fetch;
+};
+
+type Scheme = 'exact' | 'upto';
+/** One entry of x402 V2 `accepts`. */
+type PaymentRequirements = {
+    readonly scheme: Scheme;
+    readonly network: string;
+    /** Atomic units. For `upto`, the maximum at verification and the actual amount at settlement. */
+    readonly amount: string;
+    readonly asset: string;
+    readonly payTo: string;
+    readonly maxTimeoutSeconds: number;
+    readonly extra: {
+        readonly [key: string]: string;
+    };
+};
+
+/**
+ * What the ledger stores for a verified x402 payment. Settlement and reconciliation, possibly in
+ * another process, work from this record alone.
+ *
+ * `paymentPayload` carries the payer's signature, which settling after a crash needs. It never
+ * appears in errors, events, or receipts, and `redact` replaces it and `paymentRequirements` with
+ * `null` once the charge is final; everything `lookup` uses stays.
+ */
+type X402Data = {
+    readonly scheme: Scheme;
+    readonly network: string;
+    readonly asset: string;
+    readonly payTo: string;
+    readonly payer: string;
+    /** exact: the EIP-3009 bytes32 nonce, lowercase hex. upto: the Permit2 uint256 nonce, decimal. */
+    readonly nonce: string;
+    /** Unix seconds: the EIP-3009 `validBefore`, or the Permit2 `deadline`. */
+    readonly validBefore: string;
+    /** Atomic units the payer signed for: the exact value, or the upto maximum. */
+    readonly authorizedAmount: string;
+    /** The price `authorizedAmount` covers, in micro-units. upto settles at this quoted ratio. */
+    readonly limitMicros: string;
+    /** The client's PaymentPayload, forwarded unchanged to `/settle`. `null` once redacted. */
+    readonly paymentPayload: JsonObject | null;
+    /** The requirements this server derived and verified against. `null` once redacted. */
+    readonly paymentRequirements: PaymentRequirements | null;
+};
+
+type X402Rail = Rail<'x402', X402Data>;
+/**
+ * The x402 V2 rail: `exact` (EIP-3009) for fixed prices and `upto` (Permit2) for `upTo()` prices,
+ * over HTTP (`PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE`) and MCP
+ * (`_meta["x402/payment"]`). Payments are verified before the handler and settled after it.
+ *
+ * @example
+ * ```ts
+ * const toll = createTollstile({
+ *   rails: [
+ *     x402({
+ *       network: 'eip155:84532',
+ *       payTo: '0xYourAddress',
+ *       denomination: 'USD',
+ *       rpcUrl: 'https://sepolia.base.org',
+ *     }),
+ *   ],
+ *   ledger: memoryLedger(),
+ *   secret: process.env.TOLLSTILE_SECRET,
+ * });
+ * ```
+ */
+declare function x402(options: X402Options): X402Rail;
+
+export { type X402Asset, type X402Data, type X402FacilitatorOptions, type X402Options, type PaymentRequirements as X402PaymentRequirements, type X402Rail, x402 };

package/dist/index.js

@@ -0,0 +1,789 @@
+// src/x402-rail.ts
+import {
+  money,
+  TollstileError as TollstileError6,
+  toAssetUnits
+} from "tollstile";
+
+// src/facilitator.ts
+import { TollstileError as TollstileError2 } from "tollstile";
+
+// src/provider-fetch.ts
+import { TollstileError } from "tollstile";
+
+// src/wire.ts
+var BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function encodeBase64Json(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function decodeBase64Json(value) {
+  if (value.length % 4 !== 0 || !BASE64.test(value)) return { ok: false };
+  const bytes = Uint8Array.from(atob(value), (char) => char.charCodeAt(0));
+  return parseJson(new TextDecoder().decode(bytes));
+}
+function parseJson(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function textField(record, key) {
+  const value = record[key];
+  return typeof value === "string" ? value : void 0;
+}
+function objectField(record, key) {
+  const value = record[key];
+  return isObject(value) ? value : void 0;
+}
+function jsonEqual(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    const other = b;
+    return a.every((item, index) => jsonEqual(item, other[index]));
+  }
+  if (isObject(a) || isObject(b)) {
+    if (!isObject(a) || !isObject(b)) return false;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((key) => key in b && jsonEqual(a[key], b[key]));
+  }
+  return a === b;
+}
+function containsSubset(expected, actual) {
+  if (!isObject(expected)) return jsonEqual(expected, actual);
+  if (!isObject(actual)) return false;
+  return Object.entries(expected).every(([key, value]) => containsSubset(value, actual[key]));
+}
+
+// src/provider-fetch.ts
+async function postJson(fetcher, request) {
+  let status;
+  let text;
+  try {
+    const response = await fetcher(request.url, {
+      method: "POST",
+      headers: { ...request.headers, "content-type": "application/json" },
+      body: JSON.stringify(request.body),
+      signal: request.signal
+    });
+    status = response.status;
+    text = await response.text();
+  } catch (error) {
+    if (request.signal.aborted) {
+      throw new TollstileError("PROVIDER_TIMEOUT", `${request.label} did not answer in time.`, { cause: error });
+    }
+    throw new TollstileError("PROVIDER_UNAVAILABLE", `${request.label} could not be reached.`, { cause: error });
+  }
+  const parsed = parseJson(text);
+  return { status, body: parsed.ok ? parsed.value : void 0 };
+}
+
+// src/facilitator.ts
+var LABEL = "x402 facilitator";
+var REASON = /^[a-z0-9_]{1,80}$/;
+var TRANSACTION = /^0x[0-9a-fA-F]{64}$/;
+var UNEXPECTED_VERIFY = "unexpected_verify_error";
+var AMBIGUOUS_SETTLE = /* @__PURE__ */ new Set(["settlement_pending", "unexpected_settle_error"]);
+function facilitatorClient(options, fetcher) {
+  const base = options.url.replace(/\/+$/, "");
+  const post = async (path, request, operation) => postJson(fetcher, {
+    url: `${base}/${path}`,
+    body: request,
+    headers: options.headers === void 0 ? {} : await options.headers(),
+    signal: operation.signal,
+    label: `${LABEL} /${path}`
+  });
+  return {
+    async verify(request, operation) {
+      const { status, body } = await post("verify", request, operation);
+      if (!isObject(body) || typeof body.isValid !== "boolean" || body.isValid && !ok(status)) {
+        throw new TollstileError2("PROVIDER_UNAVAILABLE", `${LABEL} /verify answered HTTP ${String(status)} without a VerifyResponse.`);
+      }
+      if (body.isValid) return { isValid: true, payer: textField(body, "payer") };
+      const invalidReason = reason(textField(body, "invalidReason"), "verification_failed");
+      if (invalidReason === UNEXPECTED_VERIFY) {
+        throw new TollstileError2("PROVIDER_UNAVAILABLE", `${LABEL} /verify reported ${UNEXPECTED_VERIFY}.`);
+      }
+      return { isValid: false, invalidReason };
+    },
+    async settle(request, operation) {
+      const { status, body } = await post("settle", request, operation);
+      if (!isObject(body) || typeof body.success !== "boolean" || body.success && !ok(status)) {
+        throw new TollstileError2(
+          "PROVIDER_TIMEOUT",
+          `${LABEL} /settle answered HTTP ${String(status)} without a SettleResponse, so whether it broadcast a transfer is unknown.`
+        );
+      }
+      if (!body.success) {
+        const errorReason = reason(textField(body, "errorReason"), "settlement_failed");
+        if (AMBIGUOUS_SETTLE.has(errorReason)) {
+          throw new TollstileError2("PROVIDER_TIMEOUT", `${LABEL} /settle reported ${errorReason}; the transfer may still confirm on chain.`);
+        }
+        return { success: false, errorReason };
+      }
+      const transaction = textField(body, "transaction");
+      if (transaction === void 0 || !TRANSACTION.test(transaction)) {
+        throw new TollstileError2("PROVIDER_TIMEOUT", `${LABEL} /settle reported success without a transaction hash.`);
+      }
+      return { success: true, transaction };
+    }
+  };
+}
+function ok(status) {
+  return status >= 200 && status < 300;
+}
+function reason(value, fallback) {
+  return value !== void 0 && REASON.test(value) ? value : fallback;
+}
+
+// src/json-rpc.ts
+import { TollstileError as TollstileError3 } from "tollstile";
+var LABEL2 = "x402 JSON-RPC node";
+var QUANTITY = /^0x[0-9a-fA-F]{1,64}$/;
+var DATA = /^0x[0-9a-fA-F]*$/;
+function jsonRpcChain(url, fetcher) {
+  let id = 0;
+  const request = async (method, params, signal) => {
+    id += 1;
+    const { status, body } = await postJson(fetcher, {
+      url,
+      body: { jsonrpc: "2.0", id, method, params },
+      headers: {},
+      signal,
+      label: `${LABEL2} ${method}`
+    });
+    if (!isObject(body) || !("result" in body)) {
+      const code = isObject(body) && isObject(body.error) && typeof body.error.code === "number" ? ` (error ${String(body.error.code)})` : "";
+      throw unavailable(`${method} answered HTTP ${String(status)} without a result${code}.`);
+    }
+    return body.result ?? null;
+  };
+  return {
+    async block(tag, signal) {
+      const result = await request("eth_getBlockByNumber", [typeof tag === "bigint" ? quantity(tag) : tag, false], signal);
+      const number = isObject(result) ? hexQuantity(result, "number") : void 0;
+      const timestamp = isObject(result) ? hexQuantity(result, "timestamp") : void 0;
+      if (number === void 0 || timestamp === void 0) throw unavailable(`eth_getBlockByNumber returned no block for ${String(tag)}.`);
+      return { number, timestamp };
+    },
+    async call(to, data, block, signal) {
+      const result = await request("eth_call", [{ to, data }, quantity(block)], signal);
+      if (typeof result !== "string" || !DATA.test(result)) throw unavailable("eth_call returned malformed data.");
+      return result;
+    },
+    async logs(filter, signal) {
+      const result = await request(
+        "eth_getLogs",
+        [
+          {
+            address: filter.address,
+            topics: [...filter.topics],
+            fromBlock: quantity(filter.fromBlock),
+            toBlock: quantity(filter.toBlock)
+          }
+        ],
+        signal
+      );
+      if (!Array.isArray(result)) throw unavailable("eth_getLogs returned malformed logs.");
+      return parseLogs(result);
+    },
+    async receiptLogs(transactionHash, signal) {
+      const result = await request("eth_getTransactionReceipt", [transactionHash], signal);
+      if (!isObject(result) || !Array.isArray(result.logs)) throw unavailable(`eth_getTransactionReceipt returned no receipt for ${transactionHash}.`);
+      if (result.status !== "0x1") return [];
+      return parseLogs(result.logs);
+    },
+    async transaction(transactionHash, signal) {
+      const result = await request("eth_getTransactionByHash", [transactionHash], signal);
+      const input = isObject(result) ? textField(result, "input") : void 0;
+      if (!isObject(result) || input === void 0 || !DATA.test(input)) {
+        throw unavailable(`eth_getTransactionByHash returned no transaction for ${transactionHash}.`);
+      }
+      return { to: textField(result, "to") ?? null, input };
+    }
+  };
+}
+function parseLogs(values) {
+  return values.map((value) => {
+    const log = isObject(value) ? parseLog(value) : void 0;
+    if (log === void 0) throw unavailable("a JSON-RPC log entry is malformed.");
+    return log;
+  }).filter((log) => log !== "removed");
+}
+function parseLog(value) {
+  if (value.removed === true) return "removed";
+  const address2 = textField(value, "address");
+  const data = textField(value, "data");
+  const transactionHash = textField(value, "transactionHash");
+  const topics = Array.isArray(value.topics) ? value.topics : [];
+  if (address2 === void 0 || data === void 0 || !DATA.test(data) || transactionHash === void 0) return void 0;
+  if (!topics.every((topic) => typeof topic === "string")) return void 0;
+  return { address: address2, data, transactionHash, topics: topics.map((topic) => topic.toLowerCase()) };
+}
+function hexQuantity(record, key) {
+  const value = textField(record, key);
+  return value !== void 0 && QUANTITY.test(value) ? BigInt(value) : void 0;
+}
+function quantity(value) {
+  return `0x${value.toString(16)}`;
+}
+function unavailable(message) {
+  return new TollstileError3("PROVIDER_UNAVAILABLE", `${LABEL2}: ${message}`);
+}
+
+// src/networks.ts
+var KNOWN_NETWORKS = {
+  "eip155:8453": {
+    asset: { code: "USDC", address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6, name: "USD Coin", version: "2" },
+    testnet: false,
+    facilitator: null,
+    peg: "USD"
+  },
+  "eip155:84532": {
+    asset: { code: "USDC", address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", decimals: 6, name: "USDC", version: "2" },
+    testnet: true,
+    facilitator: "https://x402.org/facilitator",
+    peg: "USD"
+  }
+};
+var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+var UPTO_PROXY_ADDRESS = "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+var ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+function isAddress(value) {
+  return ADDRESS.test(value);
+}
+function sameAddress(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+// src/options.ts
+import { TollstileError as TollstileError4 } from "tollstile";
+var CAIP2_EVM = /^eip155:[1-9]\d{0,19}$/;
+var CURRENCY = /^[A-Z]{3}$/;
+var DEFAULT_MAX_TIMEOUT_SECONDS = 60;
+function resolveOptions(options) {
+  const { network } = options;
+  if (!CAIP2_EVM.test(network)) {
+    throw invalid(`network "${network}" is not a CAIP-2 EVM network. Use "eip155:<chainId>", e.g. "eip155:84532".`);
+  }
+  const known = KNOWN_NETWORKS[network];
+  const asset = options.asset ?? known?.asset;
+  if (asset === void 0) {
+    throw invalid(`network "${network}" has no built-in asset. Pass asset: { code, address, decimals, name, version }.`);
+  }
+  if (!isAddress(asset.address)) throw invalid(`asset address "${asset.address}" is not an EVM address.`);
+  if (!Number.isInteger(asset.decimals) || asset.decimals < 6 || asset.decimals > 18) {
+    throw invalid(`asset ${asset.code} has ${String(asset.decimals)} decimals; x402 assets need between 6 and 18.`);
+  }
+  if (!isAddress(options.payTo)) throw invalid(`payTo "${options.payTo}" is not an EVM address.`);
+  if (!URL.canParse(options.rpcUrl)) throw invalid("rpcUrl must be an absolute URL.");
+  const facilitator = options.facilitator ?? (known === void 0 || known.facilitator === null ? void 0 : { url: known.facilitator });
+  if (facilitator === void 0) {
+    throw invalid(
+      `network "${network}" needs an explicit facilitator: { url, headers }. The public x402.org facilitator is used by default only on Base Sepolia.`
+    );
+  }
+  if (!URL.canParse(facilitator.url)) throw invalid("facilitator.url must be an absolute URL.");
+  if (options.upto !== void 0 && !isAddress(options.upto.facilitatorAddress)) {
+    throw invalid(`upto.facilitatorAddress "${options.upto.facilitatorAddress}" is not an EVM address.`);
+  }
+  const maxTimeoutSeconds = options.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+  if (!Number.isInteger(maxTimeoutSeconds) || maxTimeoutSeconds <= 0) {
+    throw invalid(`maxTimeoutSeconds must be a positive integer, got ${String(maxTimeoutSeconds)}.`);
+  }
+  return {
+    network,
+    asset,
+    payTo: options.payTo,
+    basis: resolveBasis(options, known === void 0 || options.asset !== void 0 ? null : known.peg, asset.code),
+    facilitator,
+    rpcUrl: options.rpcUrl,
+    upto: options.upto ?? null,
+    maxTimeoutSeconds,
+    fetch: options.fetch ?? ((input, init) => fetch(input, init))
+  };
+}
+function resolveBasis(options, peg, code) {
+  if (options.denomination !== void 0 && options.rate !== void 0) {
+    throw invalid("set either denomination (conversion at par) or rate, not both.");
+  }
+  if (options.rate !== void 0) return { kind: "rate", rate: options.rate };
+  if (options.denomination === void 0) {
+    throw invalid(
+      `${code} needs an explicit conversion basis. Use denomination: "${peg ?? "USD"}" if one ${code} is worth one ${peg ?? "unit of your price currency"}, or rate: (price) => atomic units.`
+    );
+  }
+  if (!CURRENCY.test(options.denomination)) throw invalid(`denomination "${options.denomination}" is not a currency code like "USD".`);
+  if (peg !== null && options.denomination !== peg) {
+    throw invalid(`the built-in ${code} is pegged to ${peg}, not ${options.denomination}. Use rate for other currencies.`);
+  }
+  return { kind: "par", currency: options.denomination };
+}
+function invalid(message) {
+  return new TollstileError4("CONFIG_INVALID", `x402: ${message}`);
+}
+
+// src/payment-payload.ts
+var PAYMENT_SIGNATURE_HEADER = "payment-signature";
+var PAYMENT_META = "x402/payment";
+var UINT = /^\d{1,78}$/;
+var HEX_UINT = /^0x[0-9a-fA-F]{1,64}$/;
+var BYTES32 = /^0x[0-9a-fA-F]{64}$/;
+var MAX_UINT256 = 2n ** 256n - 1n;
+function readProof(context) {
+  const value = context.transport === "mcp" ? readMeta(context) : readHeader(context);
+  if (value === "absent") return { status: "absent" };
+  if (value === "malformed") return { status: "invalid", reason: "payload_malformed" };
+  if (value.x402Version !== 2) return { status: "invalid", reason: "unsupported_x402_version" };
+  const accepted = objectField(value, "accepted");
+  const payload = objectField(value, "payload");
+  if (accepted === void 0 || payload === void 0) return { status: "invalid", reason: "payload_malformed" };
+  return { status: "present", paymentPayload: value, accepted, payload };
+}
+function readHeader(context) {
+  const header = context.request?.headers.get(PAYMENT_SIGNATURE_HEADER);
+  if (header === null || header === void 0) return "absent";
+  const decoded = decodeBase64Json(header.trim());
+  return decoded.ok && isObject(decoded.value) ? decoded.value : "malformed";
+}
+function readMeta(context) {
+  const value = context.mcp?.meta[PAYMENT_META];
+  if (value === void 0) return "absent";
+  return isObject(value) ? value : "malformed";
+}
+var PAYMENT_IDENTIFIER_EXTENSION = "payment-identifier";
+var PAYMENT_ID = /^[a-zA-Z0-9_-]{16,128}$/;
+function paymentIdentifier(paymentPayload) {
+  const extensions = objectField(paymentPayload, "extensions");
+  const extension = extensions === void 0 ? void 0 : objectField(extensions, PAYMENT_IDENTIFIER_EXTENSION);
+  const info = extension === void 0 ? void 0 : objectField(extension, "info");
+  if (info === void 0 || info.id === void 0) return { status: "none" };
+  return typeof info.id === "string" && PAYMENT_ID.test(info.id) ? { status: "present", id: info.id } : { status: "invalid" };
+}
+function parseEip3009(payload) {
+  const authorization = objectField(payload, "authorization");
+  if (authorization === void 0 || textField(payload, "signature") === void 0) return void 0;
+  const from = address(authorization, "from");
+  const to = address(authorization, "to");
+  const value = uint(authorization, "value");
+  const validAfter = uint(authorization, "validAfter");
+  const validBefore = uint(authorization, "validBefore");
+  const nonce = textField(authorization, "nonce");
+  if (from === void 0 || to === void 0 || value === void 0 || validAfter === void 0 || validBefore === void 0 || nonce === void 0 || !BYTES32.test(nonce)) {
+    return void 0;
+  }
+  return { from, to, value, validAfter, validBefore, nonce: nonce.toLowerCase() };
+}
+function parsePermit2(payload) {
+  const authorization = objectField(payload, "permit2Authorization");
+  if (authorization === void 0 || textField(payload, "signature") === void 0) return void 0;
+  const permitted = objectField(authorization, "permitted");
+  const witness = objectField(authorization, "witness");
+  if (permitted === void 0 || witness === void 0) return void 0;
+  const from = address(authorization, "from");
+  const token = address(permitted, "token");
+  const amount = uint(permitted, "amount");
+  const spender = address(authorization, "spender");
+  const nonce = uint(authorization, "nonce");
+  const deadline = uint(authorization, "deadline");
+  const to = address(witness, "to");
+  const facilitator = address(witness, "facilitator");
+  const validAfter = uint(witness, "validAfter");
+  if (from === void 0 || token === void 0 || amount === void 0 || spender === void 0 || nonce === void 0 || deadline === void 0 || to === void 0 || facilitator === void 0 || validAfter === void 0) {
+    return void 0;
+  }
+  return { from, token, amount, spender, nonce, deadline, to, facilitator, validAfter };
+}
+function address(record, key) {
+  const value = textField(record, key);
+  return value !== void 0 && isAddress(value) ? value : void 0;
+}
+function uint(record, key) {
+  const value = textField(record, key);
+  if (value === void 0 || !(UINT.test(value) || HEX_UINT.test(value))) return void 0;
+  const parsed = BigInt(value);
+  return parsed <= MAX_UINT256 ? parsed : void 0;
+}
+
+// src/payment-requirements.ts
+var QUOTE_EXTRA_KEY = "tollstileQuote";
+function requirementsFor(settings, terms) {
+  const { asset } = settings;
+  const quote = terms.quoteToken === null ? {} : { [QUOTE_EXTRA_KEY]: terms.quoteToken };
+  const upto = terms.variable && settings.upto !== null ? { assetTransferMethod: "permit2", facilitatorAddress: settings.upto.facilitatorAddress } : {};
+  return {
+    scheme: terms.variable ? "upto" : "exact",
+    network: settings.network,
+    amount: terms.amount,
+    asset: asset.address,
+    payTo: settings.payTo,
+    maxTimeoutSeconds: settings.maxTimeoutSeconds,
+    extra: { name: asset.name, version: asset.version, ...upto, ...quote }
+  };
+}
+function acceptedMatches(requirements, accepted) {
+  const { extra, ...core } = requirements;
+  const { extra: acceptedExtra, ...acceptedCore } = accepted;
+  return jsonEqual(core, acceptedCore) && containsSubset(extra, acceptedExtra);
+}
+var PAYMENT_IDENTIFIER = {
+  info: { required: false },
+  schema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties: {
+      required: { type: "boolean" },
+      id: { type: "string", minLength: 16, maxLength: 128, pattern: "^[a-zA-Z0-9_-]+$" }
+    },
+    required: ["required"]
+  }
+};
+function paymentRequired(requirements, context) {
+  return {
+    x402Version: 2,
+    resource: { url: resourceUrl(context) },
+    accepts: [requirements],
+    extensions: { [PAYMENT_IDENTIFIER_EXTENSION]: PAYMENT_IDENTIFIER }
+  };
+}
+function resourceUrl(context) {
+  if (context.transport === "mcp" && context.mcp !== null) return `mcp://tool/${context.mcp.tool}`;
+  return context.request?.url ?? context.resource;
+}
+
+// src/settlement-lookup.ts
+import { TollstileError as TollstileError5 } from "tollstile";
+
+// src/abi.ts
+var AUTHORIZATION_STATE_SELECTOR = "0xe94a0102";
+var NONCE_BITMAP_SELECTOR = "0x4fe02b44";
+var UPTO_SETTLE_SELECTOR = "0xff11e7b4";
+var UPTO_SETTLE_WITH_PERMIT_SELECTOR = "0x016c1748";
+var TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+var AUTHORIZATION_USED_TOPIC = "0x98de503528ee59b575ef0c0a2576a82497bfc029a5685b209e9ec333479b10a5";
+var AUTHORIZATION_CANCELED_TOPIC = "0x1cdd46ff242716cdaa72d159d339a485b3438398348d68f09d7c8c0a59353d81";
+var UNORDERED_NONCE_INVALIDATION_TOPIC = "0x3704902f963766a4e561bbaab6e6cdc1b1dd12f6e9e99648da8843b3f46b918d";
+var WORD = 64;
+var HEX = /^0x(?:[0-9a-fA-F]{2})*$/;
+function word(value) {
+  const digits = typeof value === "bigint" ? value.toString(16) : value.slice(2).toLowerCase();
+  return `0x${digits.padStart(WORD, "0")}`;
+}
+function encodeCall(selector, ...words) {
+  return selector + words.map((value) => value.slice(2)).join("");
+}
+function readWord(data, index, offset = 0) {
+  if (!HEX.test(data)) return void 0;
+  const start = 2 + offset * 2 + index * WORD;
+  const slice = data.slice(start, start + WORD);
+  return slice.length === WORD ? BigInt(`0x${slice}`) : void 0;
+}
+function selectorOf(calldata) {
+  return calldata.slice(0, 10).toLowerCase();
+}
+
+// src/settlement-lookup.ts
+var CLOCK_SKEW_SECONDS = 600n;
+async function lookupSettlement(chain, data, charge, signal) {
+  const finalized = await chain.block("finalized", signal);
+  const lastValidSecond = data.scheme === "exact" ? BigInt(data.validBefore) - 1n : BigInt(data.validBefore);
+  const used = data.scheme === "exact" ? await eip3009NonceUsed(chain, data, finalized, signal) : await permit2NonceUsed(chain, data, finalized, signal);
+  if (!used) {
+    if (finalized.timestamp > lastValidSecond) return { status: "none" };
+    throw pending(`${data.payer}'s authorization is unused but valid until ${data.validBefore}; ask again after it expires.`);
+  }
+  const range = await searchRange(chain, finalized, BigInt(Math.floor(charge.createdAt.getTime() / 1e3)) - CLOCK_SKEW_SECONDS, lastValidSecond, signal);
+  const evidence = data.scheme === "exact" ? await eip3009Evidence(chain, data, range, signal) : await permit2Evidence(chain, data, range, signal);
+  if (evidence === "cancelled") return { status: "none" };
+  if (evidence === void 0) {
+    throw pending(
+      `the nonce of ${data.payer}'s authorization is used, but no settlement or cancellation was found in blocks ${String(range.fromBlock)}-${String(range.toBlock)}. Investigate before resolving by hand.`
+    );
+  }
+  return {
+    status: "settled",
+    reference: evidence.transaction,
+    details: { transaction: evidence.transaction, network: data.network, payer: data.payer, amount: evidence.amount }
+  };
+}
+async function searchRange(chain, finalized, fromSecond, lastValidSecond, signal) {
+  const back = finalized.timestamp > fromSecond ? finalized.timestamp - fromSecond : 0n;
+  const fromBlock = finalized.number > back ? finalized.number - back : 0n;
+  const start = await chain.block(fromBlock, signal);
+  const ahead = lastValidSecond > start.timestamp ? lastValidSecond - start.timestamp : 0n;
+  const toBlock = fromBlock + ahead < finalized.number ? fromBlock + ahead : finalized.number;
+  return { fromBlock, toBlock };
+}
+async function eip3009NonceUsed(chain, data, at, signal) {
+  const result = await chain.call(data.asset, encodeCall(AUTHORIZATION_STATE_SELECTOR, word(data.payer), word(data.nonce)), at.number, signal);
+  const state = readWord(result, 0);
+  if (state === void 0) throw pending("authorizationState returned malformed data.");
+  return state === 1n;
+}
+async function permit2NonceUsed(chain, data, at, signal) {
+  const nonce = BigInt(data.nonce);
+  const result = await chain.call(PERMIT2_ADDRESS, encodeCall(NONCE_BITMAP_SELECTOR, word(data.payer), word(nonce >> 8n)), at.number, signal);
+  const bitmap = readWord(result, 0);
+  if (bitmap === void 0) throw pending("Permit2 nonceBitmap returned malformed data.");
+  return (bitmap >> (nonce & 0xffn) & 1n) === 1n;
+}
+async function eip3009Evidence(chain, data, range, signal) {
+  const used = await chain.logs({ address: data.asset, topics: [AUTHORIZATION_USED_TOPIC, word(data.payer), word(data.nonce)], ...range }, signal);
+  for (const log of used) {
+    const receipt = await chain.receiptLogs(log.transactionHash, signal);
+    if (receipt.some((entry) => isTransfer(entry, data) && readWord(entry.data, 0) === BigInt(data.authorizedAmount))) {
+      return { transaction: log.transactionHash, amount: data.authorizedAmount };
+    }
+  }
+  const cancelled = await chain.logs({ address: data.asset, topics: [AUTHORIZATION_CANCELED_TOPIC, word(data.payer), word(data.nonce)], ...range }, signal);
+  return cancelled.length > 0 ? "cancelled" : void 0;
+}
+async function permit2Evidence(chain, data, range, signal) {
+  const transfers = await chain.logs({ address: data.asset, topics: [TRANSFER_TOPIC, word(data.payer), word(data.payTo)], ...range }, signal);
+  for (const log of transfers) {
+    const transaction = await chain.transaction(log.transactionHash, signal);
+    const amount = readWord(log.data, 0);
+    if (amount !== void 0 && transaction.to !== null && sameAddress(transaction.to, UPTO_PROXY_ADDRESS) && settlesNonce(transaction.input, data)) {
+      return { transaction: log.transactionHash, amount: amount.toString() };
+    }
+  }
+  const invalidations = await chain.logs({ address: PERMIT2_ADDRESS, topics: [UNORDERED_NONCE_INVALIDATION_TOPIC, word(data.payer)], ...range }, signal);
+  const nonce = BigInt(data.nonce);
+  const cancelled = invalidations.some((log) => readWord(log.data, 0) === nonce >> 8n && ((readWord(log.data, 1) ?? 0n) >> (nonce & 0xffn) & 1n) === 1n);
+  return cancelled ? "cancelled" : void 0;
+}
+var SETTLE_LAYOUTS = {
+  [UPTO_SETTLE_SELECTOR]: 0,
+  [UPTO_SETTLE_WITH_PERMIT_SELECTOR]: 5
+};
+function settlesNonce(input, data) {
+  const base = SETTLE_LAYOUTS[selectorOf(input)];
+  if (base === void 0) return false;
+  return readWord(input, base, 4) === BigInt(data.asset) && readWord(input, base + 2, 4) === BigInt(data.nonce) && readWord(input, base + 5, 4) === BigInt(data.payer);
+}
+function isTransfer(log, data) {
+  return sameAddress(log.address, data.asset) && log.topics[0] === TRANSFER_TOPIC && log.topics[1] === word(data.payer) && log.topics[2] === word(data.payTo);
+}
+function pending(message) {
+  return new TollstileError5("PROVIDER_TIMEOUT", `x402 settlement lookup: ${message}`);
+}
+
+// src/x402-rail.ts
+var PAYMENT_REQUIRED_HEADER = "payment-required";
+var PAYMENT_RESPONSE_HEADER = "payment-response";
+var PAYMENT_RESPONSE_META = "x402/payment-response";
+var NAME = "x402";
+var MAX_DATE_SECONDS = 8640000000000n;
+function x402(options) {
+  const settings = resolveOptions(options);
+  const facilitator = facilitatorClient(settings.facilitator, settings.fetch);
+  const chain = jsonRpcChain(settings.rpcUrl, settings.fetch);
+  const { asset, network } = settings;
+  return {
+    name: NAME,
+    livemode: true,
+    capabilities: {
+      // exact cannot be refunded, so the payer is charged only after the handler succeeded.
+      flows: ["authorization"],
+      authorization: "single",
+      variableAmount: settings.upto !== null,
+      quotes: true,
+      refund: false,
+      partialRefund: false,
+      lookup: true
+    },
+    async offer({ price, variable }) {
+      if (variable && settings.upto === null) return null;
+      const amount = await assetUnits(settings, price);
+      if (amount === null) return null;
+      return {
+        rail: NAME,
+        asset: { code: asset.code, network, scale: asset.decimals },
+        amount: amount.toString(),
+        basis: settings.basis.kind,
+        details: {}
+      };
+    },
+    challenge(quote, quoteToken, offer, context) {
+      const requirements = requirementsFor(settings, { amount: offer.amount, variable: quote.variable, quoteToken });
+      const body = paymentRequired(requirements, context);
+      return Promise.resolve({
+        headers: [[PAYMENT_REQUIRED_HEADER, encodeBase64Json(body)]],
+        accepts: body,
+        mcp: { style: "x402", paymentRequired: body }
+      });
+    },
+    async verify(context, terms, operation) {
+      const proof = readProof(context);
+      if (proof.status !== "present") return proof;
+      const identifier = paymentIdentifier(proof.paymentPayload);
+      if (identifier.status === "invalid") return invalid2("payment_identifier_invalid");
+      const idempotency = identifier.status === "present" ? { idempotencyKey: identifier.id } : {};
+      const extra = objectField(proof.accepted, "extra");
+      const quoteToken = extra === void 0 ? void 0 : textField(extra, QUOTE_EXTRA_KEY);
+      const priced = quoteToken === void 0 ? await routeTerms(settings, terms) : quotedTerms(settings, await terms.openQuote(quoteToken));
+      if ("status" in priced) {
+        const identified = priced.reason === "quote_invalid" ? identify(proof.payload, settings) : void 0;
+        return identified === void 0 ? priced : { ...priced, proofId: identified, ...idempotency };
+      }
+      if (priced.variable && settings.upto === null) return invalid2("variable_amount_unsupported");
+      const requirements = requirementsFor(settings, { amount: priced.amount, variable: priced.variable, quoteToken: quoteToken ?? null });
+      if (!acceptedMatches(requirements, proof.accepted)) return invalid2("accepted_mismatch");
+      const signed = requirements.scheme === "exact" ? signedEip3009(proof.payload, requirements) : signedPermit2(proof.payload, requirements, settings);
+      if ("status" in signed) return signed;
+      const verdict = await facilitator.verify({ x402Version: 2, paymentPayload: proof.paymentPayload, paymentRequirements: requirements }, operation);
+      if (!verdict.isValid) {
+        const genuine = !verdict.invalidReason.includes("signature");
+        return genuine ? { ...invalid2(verdict.invalidReason), proofId: proofIdOf(settings, signed), ...idempotency } : invalid2(verdict.invalidReason);
+      }
+      if (verdict.payer !== void 0 && !sameAddress(verdict.payer, signed.payer)) return invalid2("payer_mismatch");
+      const limit = settings.basis.kind === "par" ? money(settings.basis.currency, signed.authorizedAmount / 10n ** BigInt(asset.decimals - 6)) : priced.price;
+      const data = {
+        scheme: requirements.scheme,
+        network,
+        asset: asset.address,
+        payTo: settings.payTo,
+        payer: signed.payer,
+        nonce: signed.nonce,
+        validBefore: signed.validBefore.toString(),
+        authorizedAmount: signed.authorizedAmount.toString(),
+        limitMicros: limit.micros.toString(),
+        paymentPayload: proof.paymentPayload,
+        paymentRequirements: requirements
+      };
+      return {
+        status: "valid",
+        proofId: proofIdOf(settings, signed),
+        ...idempotency,
+        payer: signed.payer,
+        quote: priced.quote,
+        limit,
+        expiresAt: new Date(Number(signed.validBefore < MAX_DATE_SECONDS ? signed.validBefore : MAX_DATE_SECONDS) * 1e3),
+        data
+      };
+    },
+    async settle(authorization, charge, operation) {
+      const { data } = authorization;
+      if (data.paymentPayload === null || data.paymentRequirements === null) {
+        return { status: "rejected", reason: "payment_evidence_redacted" };
+      }
+      const amount = settledUnits(data, charge).toString();
+      const response = await facilitator.settle(
+        { x402Version: 2, paymentPayload: data.paymentPayload, paymentRequirements: { ...data.paymentRequirements, amount } },
+        operation
+      );
+      if (!response.success) return { status: "rejected", reason: response.errorReason };
+      return {
+        status: "settled",
+        reference: response.transaction,
+        details: { transaction: response.transaction, network: data.network, payer: data.payer, amount }
+      };
+    },
+    refund() {
+      return Promise.reject(
+        new TollstileError6("UNREACHABLE", "x402 exact and upto payments cannot be refunded, and the rail declares refund: false.")
+      );
+    },
+    // The signature expires at validBefore; there is nothing to cancel with the facilitator.
+    release() {
+      return Promise.resolve();
+    },
+    lookup(authorization, charge, operation) {
+      return lookupSettlement(chain, authorization.data, charge, operation.signal);
+    },
+    // The signature is only needed to settle; lookup works from the nonce, payer, and deadline.
+    redact(data) {
+      return { ...data, paymentPayload: null, paymentRequirements: null };
+    },
+    receipt(authorization, charge, context) {
+      if (charge.settlement === null) return { headers: [], meta: {} };
+      const { data } = authorization;
+      const response = {
+        success: true,
+        transaction: charge.settlement.reference,
+        network: data.network,
+        payer: data.payer,
+        amount: settledUnits(data, charge).toString()
+      };
+      return context.transport === "mcp" ? { headers: [], meta: { [PAYMENT_RESPONSE_META]: response } } : { headers: [[PAYMENT_RESPONSE_HEADER, encodeBase64Json(response)]], meta: {} };
+    }
+  };
+}
+function quotedTerms(settings, quote) {
+  if (quote === void 0) return invalid2("quote_invalid");
+  const offer = quote.offers.find((candidate) => candidate.rail === NAME);
+  if (offer === void 0) return invalid2("quote_offer_missing");
+  const { asset } = offer;
+  if (asset.network !== settings.network || asset.code !== settings.asset.code || asset.scale !== settings.asset.decimals) {
+    return invalid2("quote_offer_mismatch");
+  }
+  return { price: quote.price, amount: offer.amount, variable: quote.variable, quote };
+}
+async function routeTerms(settings, terms) {
+  if (terms.price === null) return invalid2("quote_required");
+  const amount = await assetUnits(settings, terms.price);
+  if (amount === null) return invalid2("price_unsupported");
+  return { price: terms.price, amount: amount.toString(), variable: terms.variable, quote: null };
+}
+async function assetUnits(settings, price) {
+  const { basis, asset } = settings;
+  if (basis.kind === "par") return price.currency === basis.currency ? toAssetUnits(price, asset.decimals) : null;
+  const amount = await basis.rate(price);
+  if (amount <= 0n) {
+    throw new TollstileError6("CONFIG_INVALID", `x402: rate() converted a price to ${amount.toString()} ${asset.code} units; it must be positive.`);
+  }
+  return amount;
+}
+function proofIdOf(settings, signed) {
+  return [settings.network, settings.asset.address, signed.payer, signed.nonce].join(":").toLowerCase();
+}
+function identify(payload, settings) {
+  const eip3009 = parseEip3009(payload);
+  if (eip3009 !== void 0) return proofIdOf(settings, { payer: eip3009.from.toLowerCase(), nonce: eip3009.nonce });
+  const permit2 = parsePermit2(payload);
+  return permit2 === void 0 ? void 0 : proofIdOf(settings, { payer: permit2.from.toLowerCase(), nonce: permit2.nonce.toString() });
+}
+function signedEip3009(payload, requirements) {
+  const authorization = parseEip3009(payload);
+  if (authorization === void 0) return invalid2("payload_invalid");
+  if (!sameAddress(authorization.to, requirements.payTo)) return invalid2("recipient_mismatch");
+  if (authorization.value !== BigInt(requirements.amount)) return invalid2("amount_mismatch");
+  return {
+    payer: authorization.from.toLowerCase(),
+    nonce: authorization.nonce,
+    validBefore: authorization.validBefore,
+    authorizedAmount: authorization.value
+  };
+}
+function signedPermit2(payload, requirements, settings) {
+  const authorization = parsePermit2(payload);
+  if (authorization === void 0 || settings.upto === null) return invalid2("payload_invalid");
+  if (!sameAddress(authorization.token, requirements.asset)) return invalid2("asset_mismatch");
+  if (!sameAddress(authorization.to, requirements.payTo)) return invalid2("recipient_mismatch");
+  if (authorization.amount !== BigInt(requirements.amount)) return invalid2("amount_mismatch");
+  if (!sameAddress(authorization.spender, UPTO_PROXY_ADDRESS)) return invalid2("spender_mismatch");
+  if (!sameAddress(authorization.facilitator, settings.upto.facilitatorAddress)) return invalid2("facilitator_mismatch");
+  return {
+    payer: authorization.from.toLowerCase(),
+    nonce: authorization.nonce.toString(),
+    validBefore: authorization.deadline,
+    authorizedAmount: authorization.amount
+  };
+}
+function settledUnits(data, charge) {
+  const authorized = BigInt(data.authorizedAmount);
+  if (data.scheme === "exact") return authorized;
+  return authorized * charge.amount.micros / BigInt(data.limitMicros);
+}
+function invalid2(reason2) {
+  return { status: "invalid", reason: reason2 };
+}
+export {
+  x402
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tollstile/x402",
+  "version": "0.1.0",
+  "description": "x402 payments for APIs and MCP tools: accept USDC with the exact and upto schemes, verify through a facilitator, and reconcile on-chain. A Tollstile rail.",
+  "keywords": [
+    "x402",
+    "x402-server",
+    "usdc",
+    "base",
+    "stablecoin",
+    "agent-payments",
+    "machine-payments",
+    "ai-agents",
+    "mcp-payments",
+    "api-monetization",
+    "pay-per-call",
+    "http-402"
+  ],
+  "homepage": "https://tollstile.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tollstile/tollstile.git",
+    "directory": "packages/x402"
+  },
+  "bugs": {
+    "url": "https://github.com/tollstile/tollstile/issues"
+  },
+  "author": "Paradigm AI Inc.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "tollstile": "^0.1.0"
+  },
+  "devDependencies": {
+    "@x402/core": "2.25.0",
+    "tollstile": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}