@odatano/x402 0.1.0 → 0.2.0

package/.github/workflows/test.yaml

@@ -0,0 +1,49 @@
+name: tests
+
+# Run on every push to main and every pull request. Manual dispatch
+# lets us re-run the workflow from the Actions tab without a commit.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Node ${{ matrix.node }} on ubuntu-latest
+    runs-on: ubuntu-latest
+
+    strategy:
+      # One Node failing should not cancel the other matrix legs;
+      # often a regression hits one version only.
+      fail-fast: false
+      matrix:
+        # Matches ODATANO core's support range.
+        node: ['20.x', '22.x']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node ${{ matrix.node }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        # `npm ci` enforces the lockfile and refuses to mutate it.
+        # Faster and more deterministic than `npm install` for CI.
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type-check + build
+        # tsc -p tsconfig.build.json emits .js/.d.ts next to .ts.
+        # We don't ship those emits from CI; the step just verifies
+        # the build passes against the declared types.
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to `@odatano/x402` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/) and the project adheres to [Semantic Versioning](https://semver.org/).
+
+**Pre-1.0 caveat:** minor versions may include breaking changes until `1.0.0`.
+
+## [0.2.0] - 2026-05-15
+
+### Added
+- **Client helpers**: `x402Fetch`, `x402Axios`, `createBridgePayHandler`, `encodePaymentEnvelope` for symmetric server + client usage. See [`docs/usage.md`](docs/usage.md#5-client-side-auto-handle-402-x402fetch--x402axios).
+- **Facilitator adapter pattern**: `Facilitator` interface, `localFacilitator()` (default, in-process via `@odatano/core`), `httpFacilitator()` for delegating verify+settle to a hosted service. HTTP wire format documented in [`docs/facilitator-protocol.md`](docs/facilitator-protocol.md).
+- **`facilitator` option** on `gateService` and `x402Middleware` for swapping in the local default, an HTTP delegate, or a mock for tests.
+- **GitHub Actions CI** (`.github/workflows/test.yaml`): runs lint + build + tests on Node 20.x and 22.x for every push to `main` and every pull request.
+
+### Changed
+- Test count: 144 → 177 (added 4 client suites and 2 facilitator-adapter suites).
+
+### Notes
+- `0.1.0` consumers upgrade without code changes. The new `facilitator` option defaults to the previous in-process behaviour, so existing call sites are untouched.
+
+## [0.1.0] - 2026-05-13
+
+### Added
+- Initial release. Cardano-x402-v2 payment gating for SAP CAP and Express.
+- `gateService(srv, opts)` for CAP `before('*')` integration.
+- `x402Middleware(opts)` for plain Express routes.
+- Facilitator pipeline: decode, validate (six mandatory checks), `checkNonceUnspent`, `settle` (submit + poll-until-confirmed), `onAccepted` audit callback.
+- Helpers: `verifyConfirmedPayment` (post-paid flow), `buildUnsignedPaymentTx` (browser-buyer flow).
+- CAP plugin auto-discovery via `cds-plugin.js`.
+- 144 unit tests across 13 suites.
+
+### Spec compatibility
+- Implements Cardano-x402-**v2** only. v1 envelopes are rejected with `unsupported_version`; v1-style network strings (`cardano-preprod` with hyphen) are rejected with `invalid_network_format`.
+- v1 and v2 facilitators cannot share a route: they use different header names (`X-PAYMENT` vs `PAYMENT-SIGNATURE`) and incompatible 402 bodies. To migrate from v1, replace the middleware in one commit; clients must upgrade simultaneously.

package/README.md

@@ -2,31 +2,19 @@
 
 x402 payment gating for SAP CAP applications, backed by Cardano.
 
-Wire a single `before('*')` hook into your CAP service and every gated request returns **HTTP 402 Payment Required** until the caller proves on-chain settlement. Asset-agnostic — pay in ADA, USDM, or any native asset.
+Wire a single `before('*')` hook into your CAP service. Every gated request returns **HTTP 402 Payment Required** until the caller proves on-chain settlement. Asset-agnostic: pay in ADA, USDM, or any native asset.
 
 Implements the **Cardano-x402-v2** spec on top of [`@odatano/core`](https://www.npmjs.com/package/@odatano/core).
 
----
-
-## What is x402?
-
-[x402](https://www.x402.org/) is the dormant HTTP `402 Payment Required` status code, revived. Servers respond `402` with a machine-readable body describing the price, asset, and recipient. Clients build, sign, and submit a payment, then retry the request with a `PAYMENT-SIGNATURE` header. Settlement happens on-chain.
-
-The original x402 spec is Coinbase / EVM-flavoured. The **Cardano-x402-v2** spec (in progress at [masumi-network/x402-cardano](https://github.com/masumi-network/x402-cardano)) adapts it to Cardano's UTxO model. This library is a from-scratch v2 implementation in TypeScript.
-
----
-
 ## Install
 
 ```bash
 npm install @odatano/x402 @odatano/core
 ```
 
-`@odatano/core` (the Cardano bridge) is a peer dependency — install whichever version meets `>=1.7.8`.
-
----
+`@odatano/core` (the Cardano bridge) is a peer dependency. Install whichever version meets `>=1.7.8`.
 
-## Quick Start — CAP service gate
+## Quick Start
 
 ```typescript
 // srv/prices-service.ts
@@ -38,16 +26,10 @@ export class PricesService extends cds.ApplicationService {
     gateService(this, {
       payTo:   'addr_test1...your-preprod-address...',
       network: 'cardano:preprod',
-      asset:   'lovelace',                  // or '<policy>.<nameHex>' for native tokens
+      asset:   'lovelace',                // or '<policy>.<nameHex>' for native tokens
       routePricing: {
-        Quotes:        '500000',            // 0.5 ADA per Quotes read
-        getBestPrice:  '1000000',           // 1 ADA per getBestPrice action call
-      },
-      description: 'Synthetic price feed',
-      onAccepted: async (claim, req) => {
-        // Optional audit — runs once per accepted payment, after settlement.
-        // Errors here are logged but don't block the response.
-        console.log(`paid ${claim.amountUnits} ${claim.asset} (tx=${claim.txHash})`);
+        Quotes:       '500000',           // 0.5 ADA per Quotes read
+        getBestPrice: '1000000',          // 1 ADA per getBestPrice action call
       },
     });
     return super.init();
@@ -71,280 +53,41 @@ Configure the Cardano backend in `package.json`:
 }
 ```
 
-That's it — `cds watch` and every request to a gated route gets:
-
-```http
-HTTP/1.1 402 Payment Required
-Content-Type: application/json
-```
-```json
-{
-  "x402Version": 2,
-  "error": "PAYMENT-SIGNATURE header is required",
-  "accepts": [{
-    "scheme": "exact",
-    "network": "cardano:preprod",
-    "asset": "lovelace",
-    "amount": "500000",
-    "payTo": "addr_test1...",
-    "resource": {
-      "url": "/odata/v4/prices/Quotes",
-      "description": "Synthetic price feed",
-      "mimeType": "application/json"
-    },
-    "assetTransferMethod": "default",
-    "maxTimeoutSeconds": 600
-  }]
-}
-```
-
-A working version of this is in [`examples/cap-app/`](examples/cap-app/).
-
----
-
-## Usage patterns
-
-### 1. CAP service gate (`gateService`)
-
-For OData-served entities and bound/unbound actions. Pricing keys can be entity names (for CRUD) or action names — the gate tries both.
-
-```typescript
-gateService(this, {
-  payTo, network, asset,
-  routePricing: { Quotes: '500000', getBestPrice: '1000000' },
-});
-```
-
-When a payment is accepted, the verified `PaymentClaim` is stashed on `req.payment` for downstream handlers, and an `X-PAYMENT-RESPONSE` header is set on the response.
+`cds watch`, then probe a gated route: it returns `402` with a v2-shape body. A working example lives in [`examples/cap-app/`](examples/cap-app/).
 
-### 2. Express middleware (`x402Middleware`)
+## What's in the box
 
-For plain Express routes (e.g. mounted alongside CAP via `cds.on('bootstrap', app => …)`):
-
-```typescript
-import { x402Middleware } from '@odatano/x402';
-
-app.use('/api/premium', x402Middleware({
-  payTo, network, asset,
-  priceUnits: '1000000',
-  skipPaths: /(\$metadata|^\/?$)/i,
-  onAccepted: async (claim, req) => { /* audit */ },
-}));
-```
-
-### 3. Programmatic — verify a post-paid tx
-
-For subscription / pre-paid flows where the buyer hands you a tx hash:
-
-```typescript
-import { verifyConfirmedPayment } from '@odatano/x402';
-
-const result = await verifyConfirmedPayment({
-  txHash:         'ab8f…',
-  requiredAmount: '1000000',
-  asset:          'lovelace',
-  payTo:          'addr_test1...',
-  network:        'cardano:preprod',
-});
-
-if (result.ok) {
-  // result.amountUnits is what was actually paid (may exceed requiredAmount)
-} else {
-  // result.code: 'pending' | 'wrong_asset' | 'insufficient_amount' | ...
-}
-```
-
-### 4. Programmatic — server-side unsigned-tx builder for browser buyers
-
-When the buyer's CIP-30 wallet can sign but not coin-select:
-
-```typescript
-import { buildUnsignedPaymentTx, buildPaymentRequirements, flatRequirements } from '@odatano/x402';
-
-const body = buildPaymentRequirements({ amount: '1000000', asset: 'lovelace', payTo, network: 'cardano:preprod', resource: '/r' });
-const requirements = flatRequirements(body);
-
-const { unsignedTxCborHex, txHashHex, nonceRef } = await buildUnsignedPaymentTx({
-  buyerBech32: 'addr_test1...buyer...',
-  requirements,
-});
-
-// Browser signs unsignedTxCborHex via CIP-30, then assembles the
-// PAYMENT-SIGNATURE envelope with `nonceRef` as payload.nonce.
-```
+- **`gateService(srv, opts)`** for CAP services and **`x402Middleware(opts)`** for plain Express routes.
+- **`x402Fetch` / `x402Axios`** wrappers that auto-handle 402 on the client side.
+- **`Facilitator` adapter:** `localFacilitator()` (default, in-process via `@odatano/core`) or `httpFacilitator()` to delegate verify+settle to a hosted service.
+- **Helpers:** `buildUnsignedPaymentTx` (browser-buyer flow), `verifyConfirmedPayment` (post-paid / subscription).
 
----
+## Documentation
 
-## Configuration reference
-
-### `gateService(srv, options)` / `x402Middleware(options)`
-
-| Option | Type | Required | Default | Notes |
-|---|---|---|---|---|
-| `payTo` | `string` (bech32) | yes | — | Recipient address |
-| `network` | `'cardano:mainnet' \| 'cardano:preprod' \| 'cardano:preview'` | yes | — | **v2 uses colon separator** (v1 hyphen rejected) |
-| `asset` | `string` | yes | — | `'lovelace'` for ADA, or `'<policyIdHex>.<assetNameHex>'` for native tokens |
-| `priceUnits` | `string \| number \| bigint` | one of priceUnits / routePricing | — | Single price for everything under the mount |
-| `routePricing` | `Record<string, string \| number \| bigint>` | one of priceUnits / routePricing | — | Per-entity / per-action prices. Unmapped keys pass through unless `priceUnits` is also set |
-| `skipPaths` | `RegExp` | no | matches `$metadata`, `$batch`, root, `/index` | Express only — paths to bypass |
-| `description` | `string` | no | `''` | Embedded in `accepts[0].resource.description` |
-| `mimeType` | `string` | no | `'application/json'` | Embedded in `accepts[0].resource.mimeType` |
-| `assetTransferMethod` | `'default' \| 'masumi' \| 'script'` | no | `'default'` | v2 field; MVP supports only `default` |
-| `maxTimeoutSeconds` | `number` | no | `600` | Buyer-side TTL hint |
-| `extra` | `Record<string, unknown>` | no | — | Free-form extras (decimals, fingerprint, UI hints) |
-| `settlePollBudgetMs` | `number` | no | `60_000` | How long to poll for chain confirmation before returning `402 pending` |
-| `allowNoTtl` | `boolean` | no | `false` | If `true`, accept txs with no validity-range upper bound |
-| `onAccepted` | `(claim, req) => void \| Promise<void>` | no | — | Audit callback. Errors logged, never block response |
-| `resourceUrl` | `(req) => string` | no (CAP only) | derives from `req.http.req.originalUrl` | Override the resource URL emitted in the 402 body |
-
----
-
-## The buyer flow
-
-```
-        Server                              Buyer (browser / CLI)
-          │                                       │
-          │  ◄── GET /odata/v4/prices/Quotes ─────│
-          │                                       │
-          │ ──── 402 + accepts[0] (price, payTo) ►│
-          │                                       │
-          │                              ┌────────┴────────┐
-          │                              │ build tx        │
-          │                              │ sign via CIP-30 │
-          │                              │ base64-encode   │
-          │                              └────────┬────────┘
-          │                                       │
-          │  ◄── GET /odata/v4/prices/Quotes ─────│
-          │        PAYMENT-SIGNATURE: <base64>    │
-          │                                       │
-   ┌──────┴──────┐                                │
-   │ 6 checks    │                                │
-   │ + submit    │                                │
-   │ + poll      │                                │
-   │ + onAccepted│                                │
-   └──────┬──────┘                                │
-          │                                       │
-          │ ─────── 200 OK + data ───────────────►│
-          │   X-PAYMENT-RESPONSE: <base64>        │
-```
-
-`PAYMENT-SIGNATURE` envelope shape:
-
-```json
-{
-  "x402Version": 2,
-  "scheme": "exact",
-  "network": "cardano:preprod",
-  "payload": {
-    "transaction": "<base64-CBOR of signed tx>",
-    "nonce":       "<txHash>#<outputIndex>"
-  }
-}
-```
-
-The `nonce` references a UTxO that **must also appear as an input of the payment tx**. Once the tx settles, that UTxO is consumed — replay defense is on-chain, no DB table needed.
-
----
-
-## Six mandatory facilitator checks
-
-Every accepted payment passes all six (in order):
-
-| # | Check | Code on failure |
-|---|---|---|
-| 1 | Network matches requirements | `network_mismatch` |
-| 2 | At least one output to `payTo` | `wrong_recipient` |
-| 3 | Sum of payTo outputs for asset ≥ required | `insufficient_amount` |
-| 4 | Exact policy + asset-name match | `wrong_asset` |
-| 5 | Nonce UTxO referenced as tx input **and** unspent on chain | `nonce_not_referenced` / `replay_detected` |
-| 6 | Validity-range upper bound still in future | `expired_ttl` |
-
-Plus a sanity guard: tx has at least one vkey witness → `unsigned_transaction`.
-
-Rejected requests get `402` with an `error` field of the form `"<base> (<code>): <reason>"` so clients can parse the code without breaking wire format.
-
----
-
-## Architecture
-
-```
-            ┌──────────────────┐
-  consumer  │ CAP application  │
-            │                  │
-            │ gateService(this,│
-            │   { … })         │
-            └────────┬─────────┘
-                     │
-                     ▼
-            ┌──────────────────┐    bridge.ts
-            │  @odatano/x402   │ ──────────────┐
-            │                  │               │
-            │ core/      ──────┤ pure logic    │
-            │ facilitator/ ────┤ chain-touching│
-            │ middleware/  ────┤ Express + CAP │
-            │ helpers/     ────┤ tx-build,     │
-            │                  │ verify-post-paid
-            └──────────────────┘               │
-                                               ▼
-                                  ┌────────────────────────┐
-                                  │   @odatano/core 1.7.8  │
-                                  │  ┌──────┬──────┬─────┐ │
-                                  │  │ Blkf │Koios │Ogms │ │
-                                  │  └──────┴──────┴─────┘ │
-                                  └────────────────────────┘
-                                            │
-                                            ▼
-                                       Cardano network
-```
-
-Pure modules (`core/*`) are decoupled from the bridge and can be unit-tested without any chain backend. The facilitator orchestrates `decode → validate → checkNonceUnspent → settle → onAccepted`.
-
----
+| Doc | Covers |
+|---|---|
+| [`docs/usage.md`](docs/usage.md) | All five usage patterns + full configuration reference |
+| [`docs/protocol.md`](docs/protocol.md) | Buyer-flow diagram, `PAYMENT-SIGNATURE` envelope, the six mandatory facilitator checks |
+| [`docs/architecture.md`](docs/architecture.md) | Module layout, pure-vs-chain split, plugin auto-discovery |
+| [`docs/facilitator-protocol.md`](docs/facilitator-protocol.md) | HTTP wire format for the hosted-facilitator pattern (`httpFacilitator()`) |
+| [`CHANGELOG.md`](CHANGELOG.md) | Versioned changes, latest first |
 
 ## Requirements
 
 - Node.js 22+
 - `@sap/cds >= 9` (peer)
 - `@odatano/core >= 1.7.8` (peer)
-- `express ^4` (peer) — only required if you use `x402Middleware`
+- `express ^4` (peer), only if you use `x402Middleware`
 - A Cardano backend reachable via `@odatano/core` (Blockfrost / Koios / Ogmios)
 
----
-
 ## Development
 
 ```bash
-npm install                # Workspace install — covers root + examples/*
-npm run build              # tsc — emits .js/.d.ts next to .ts (outDir: .)
-npm test                   # 144 tests, ~12s
-npm run test:coverage      # Coverage report
-npm run watch              # cds watch — for the root project itself
-```
-
-The example app:
-
-```bash
-cd examples/cap-app
-npm start                  # cds-serve with in-memory SQLite
-```
-
-Then probe:
-
-```bash
-curl -s http://localhost:4004/odata/v4/prices/Quotes | jq .
-# → 402 with v2 body
+npm install                # Workspace install: covers root + examples/*
+npm run build              # tsc, emits .js/.d.ts next to .ts (outDir: .)
+npm test                   # 177 tests, ~13s
 ```
 
----
-
-## Versioning + spec compatibility
-
-- **Library:** `0.1.0` (pre-1.0; expect minor breakages between minors until 1.0)
-- **Spec:** Cardano-x402-**v2** only. v1 envelopes are rejected with `unsupported_version`. v1-style network strings (`cardano-preprod`) are rejected with `invalid_network_format`.
-- **Coexistence:** A v1 facilitator and a v2 facilitator can't share the same route — they use different header names (`X-PAYMENT` vs `PAYMENT-SIGNATURE`) and incompatible 402 bodies. To migrate from v1, replace the middleware in one commit; clients must upgrade simultaneously.
-
----
-
 ## License
 
 Apache-2.0.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@odatano/x402",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "x402 Cardano-v2 payment library for SAP CAP applications",
   "license": "Apache-2.0",
   "main": "srv/index.js",
-  "types": "srv/index.d.ts",
+  "types": "srv/cds-augment.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -26,10 +26,16 @@
     "@emurgo/cardano-serialization-lib-nodejs": "^15.0.3"
   },
   "peerDependencies": {
+    "@cap-js/cds-types": ">=0.15",
     "@odatano/core": ">=1.7.8",
     "@sap/cds": ">=9",
     "express": "^4"
   },
+  "peerDependenciesMeta": {
+    "@cap-js/cds-types": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cap-js/cds-types": "^0.15.0",
     "@cap-js/cds-typer": "^0.38.0",

package/srv/cds-augment.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="@cap-js/cds-types" />
+/**
+ * Public types entry — hand-written wrapper around the generated barrel.
+ *
+ * Why this file exists: the triple-slash reference below is the only
+ * way to ship `@cap-js/cds-types`' module-augmentation of `@sap/cds`
+ * to TypeScript consumers without forcing them to mutate their own
+ * tsconfig. References authored inside `.ts` sources get stripped by
+ * tsc during `.d.ts` emit — references in hand-written `.d.ts` files
+ * are preserved verbatim, so we use a hand-written one as the
+ * advertised `types` entry in package.json.
+ *
+ * Consumers should still install `@cap-js/cds-types` (declared as an
+ * optional peer dependency) — this file only routes the augmentation
+ * once that package is resolvable.
+ */
+export * from './index';

package/srv/client/axios.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `x402Axios` — attach a response interceptor to an existing axios
+ * instance so 402 responses trigger a payment and retry.
+ *
+ * **No hard axios dependency.** We use structural typing for the
+ * instance: anything with the standard axios shape (interceptors,
+ * request, defaults.headers) works. Verified against axios 1.x.
+ *
+ * Usage:
+ *   import axios from 'axios';
+ *   import { x402Axios, createBridgePayHandler } from '@odatano/x402';
+ *
+ *   const client = x402Axios(axios.create({ baseURL: '...' }), {
+ *     pay: createBridgePayHandler({ buyerBech32, signTx }),
+ *   });
+ *   await client.get('/api/premium/foo');   // returns 200 after pay
+ */
+import type { X402ClientOptions } from './types';
+interface AxiosRequestConfigLike {
+    headers?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+interface AxiosInstanceLike {
+    interceptors: {
+        response: {
+            use: (onFulfilled: (res: unknown) => unknown, onRejected: (err: unknown) => unknown) => number;
+        };
+    };
+    request: (cfg: AxiosRequestConfigLike) => Promise<unknown>;
+}
+/**
+ * Attach the x402 response interceptor in-place and return the same
+ * instance for chaining. The interceptor only fires on 402 responses;
+ * everything else passes through unchanged.
+ */
+export declare function x402Axios<T extends AxiosInstanceLike>(instance: T, opts: X402ClientOptions): T;
+export {};
+//# sourceMappingURL=axios.d.ts.map

package/srv/client/axios.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * `x402Axios` — attach a response interceptor to an existing axios
+ * instance so 402 responses trigger a payment and retry.
+ *
+ * **No hard axios dependency.** We use structural typing for the
+ * instance: anything with the standard axios shape (interceptors,
+ * request, defaults.headers) works. Verified against axios 1.x.
+ *
+ * Usage:
+ *   import axios from 'axios';
+ *   import { x402Axios, createBridgePayHandler } from '@odatano/x402';
+ *
+ *   const client = x402Axios(axios.create({ baseURL: '...' }), {
+ *     pay: createBridgePayHandler({ buyerBech32, signTx }),
+ *   });
+ *   await client.get('/api/premium/foo');   // returns 200 after pay
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.x402Axios = x402Axios;
+const envelope_1 = require("./envelope");
+// Marker key on the config to break infinite-retry loops.
+const RETRY_KEY = '__x402_x402Retries';
+function isAxiosError(e) {
+    return !!e && typeof e === 'object' && 'response' in e;
+}
+/**
+ * Attach the x402 response interceptor in-place and return the same
+ * instance for chaining. The interceptor only fires on 402 responses;
+ * everything else passes through unchanged.
+ */
+function x402Axios(instance, opts) {
+    if (typeof opts?.pay !== 'function') {
+        throw new TypeError('x402Axios: opts.pay must be a function');
+    }
+    const maxRetries = opts.maxRetries ?? 1;
+    const selectFirst = (a) => a[0];
+    const select = opts.selectAccepts ?? selectFirst;
+    instance.interceptors.response.use((response) => response, async (error) => {
+        if (!isAxiosError(error) || error.response?.status !== 402 || !error.config) {
+            throw error;
+        }
+        const cfg = error.config;
+        const retries = Number(cfg[RETRY_KEY] ?? 0);
+        if (retries >= maxRetries)
+            throw error;
+        const body = error.response.data;
+        if (body?.x402Version !== 2 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+            throw error;
+        }
+        const chosen = select(body.accepts);
+        if (!chosen)
+            throw error;
+        const { signedTxCborHex, nonceRef } = await opts.pay(chosen);
+        const header = (0, envelope_1.encodePaymentEnvelope)({
+            network: chosen.network,
+            signedTxCborHex,
+            nonceRef,
+        });
+        const nextCfg = {
+            ...cfg,
+            headers: { ...(cfg.headers ?? {}), 'PAYMENT-SIGNATURE': header },
+            [RETRY_KEY]: retries + 1,
+        };
+        return instance.request(nextCfg);
+    });
+    return instance;
+}

package/srv/client/envelope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build the `PAYMENT-SIGNATURE` header value for a Cardano-x402-v2 retry.
+ *
+ * Inverse of `srv/core/decode.ts`. The wire format is:
+ *
+ *   PAYMENT-SIGNATURE: base64(JSON.stringify({
+ *     x402Version: 2,
+ *     scheme: 'exact',
+ *     network: 'cardano:preprod' | 'cardano:mainnet' | 'cardano:preview',
+ *     payload: {
+ *       transaction: '<base64 CBOR of signed tx>',
+ *       nonce:       '<txHash>#<outputIndex>'
+ *     }
+ *   }))
+ *
+ * Pure function — no chain calls, no I/O. Callable from any runtime
+ * that has `Buffer` (Node) or a polyfill (browser bundlers usually
+ * provide one via `buffer`).
+ */
+import type { Network } from '../core/network';
+export interface EncodeEnvelopeArgs {
+    network: Network;
+    /** Hex of the SIGNED payment tx (vkey witnesses already attached). */
+    signedTxCborHex: string;
+    /** `<txHash>#<outputIndex>` UTxO-ref nonce. */
+    nonceRef: string;
+}
+/**
+ * Encode the v2 PAYMENT-SIGNATURE envelope. Validates shape eagerly so
+ * a malformed call fails here, not on the server's `decode()`.
+ */
+export declare function encodePaymentEnvelope(args: EncodeEnvelopeArgs): string;
+//# sourceMappingURL=envelope.d.ts.map