@piprail/sdk 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.13.0] — 2026-06-10
+
+### Added — gate `discovery` option (one flag → x402scan-listable)
+- **`createPaymentGate`/`requirePayment` now take an opt-in `discovery` option** that emits an
+  `extensions.bazaar` block **in the 402 challenge itself** — so the gate alone satisfies x402scan's
+  mandatory input-schema check (no separately-served file needed). `discovery: true` for a no-input
+  GET, or a `DiscoveryDescriptor` (`{ method, queryParams, output }`). Omitting it leaves the challenge
+  byte-identical. New export `buildBazaarExtension` + the `DiscoveryDescriptor`/`BazaarExtension` types.
+- `DomainClaim` now also surfaces `verificationToken`, and `verificationHash` is **always** populated —
+  from the API, or computed as `sha256(verificationToken)` — so an agent always has the exact bytes to serve.
+
+### Fixed — conformance bug hunt (20-agent audit, every finding verified against the live API)
+- **`hostOf` returned `''` for a bare `host:port`** (`new URL('x.com:8080')` parses the host as a scheme) —
+  `claimDomain`/`verifyDomain` now extract the host correctly.
+- **`indexes.ts` base64 was Latin1-only** (`btoa`) — now UTF-8-safe, matching `x402.ts` (a non-ASCII SIWX
+  field could have thrown in the browser).
+- **SIWX message** now reads `chainId` from `supportedChains[]` as a fallback (not only `info.chainId`),
+  so it always signs the correct `Chain ID`.
+- Removed an invented `x-payment-info.bazaar:{discoverable:true}` marker from `buildOpenApi` (no index read it).
+- Documented the caveat that the open indexes' agents are standard `exact` clients — advertise an `exact`
+  rail to be *payable*, not just listed (README + the `piprail_register` MCP tool).
+
 ## [1.12.0] — 2026-06-09
 
 ### Added — One-call domain verification (pending-review → searchable)
@@ -593,6 +615,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.13.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.12.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.11.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.10.0]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -206,22 +206,34 @@ listing won't appear here, so don't read that absence as failure. `network` defa
 chain); pass `'any'` for every chain, or a CAIP-2 id (`'eip155:8453'`). Slugs map to CAIP-2 via
 `SLUG_TO_CAIP2`; an unresolved network is kept, never hidden.
 
-**4) Make your endpoint self-describing** — turn your gate's config into the artifacts a crawler reads
-(pure, no I/O); serve them on **your own** origin. **x402scan REQUIRES** a resolvable input schema (your
-`/openapi.json` or an `extensions.bazaar` block in the 402 body), so this is what makes an x402scan
-listing accepted:
+**4) Make your endpoint self-describing.** **x402scan REQUIRES an input schema or it won't list you.**
+The simplest path: set the gate's `discovery` option — it emits an `extensions.bazaar` block **in the 402
+itself**, so the challenge alone is x402scan-listable (no extra file to serve):
 
 ```ts
-import { createPaymentGate, buildOpenApi, buildWellKnownX402, buildX402DnsTxt } from '@piprail/sdk'
+// `discovery: true` for a no-input GET, or describe the request:
+const gate = createPaymentGate({
+  chain: 'base', token: 'USDC', amount: '0.05', payTo,
+  exact: { settle: { facilitator: 'https://facilitator.payai.network' } }, // be payable by exact clients (see caveat)
+  discovery: { method: 'GET', output: { type: 'json', example: { ok: true } } },
+})
+```
 
-const gate = createPaymentGate({ chain: 'base', token: 'USDC', amount: '0.05', payTo })
+Optionally also serve the static discovery files (richer listings; OpenAPI carries the `x-generator`
+attribution stamp) from your own origin — all pure, no I/O:
+
+```ts
+import { buildOpenApi, buildWellKnownX402, buildX402DnsTxt } from '@piprail/sdk'
 const desc = await gate.describe('https://api.example.com/report')
-const openapi = buildOpenApi({ origin: 'https://api.example.com', resources: [desc] })
-// serve at /openapi.json — each priced op carries an `x-payment-info` block + a root `x-generator` stamp.
-const wellKnown = buildWellKnownX402({ resources: [desc] }) // serve at /.well-known/x402
+const openapi = buildOpenApi({ origin: 'https://api.example.com', resources: [desc] }) // → /openapi.json
+const wellKnown = buildWellKnownX402({ resources: [desc] })                            // → /.well-known/x402
 // buildX402DnsTxt(...) emits the _x402 DNS line too.
 ```
 
+> **Caveat — be *payable*, not just listed.** The open indexes' agents are overwhelmingly standard
+> `exact` clients; a default `onchain-proof`-only gate gets listed but they can't pay it. Advertise an
+> `exact` rail (above) so a discovered resource is actually payable.
+
 **Know each index before you call** — the facts are one import, `DIRECTORY_INFO`, and `register()`
 projects them onto every outcome (`visibility` + `note`), so an agent never has to guess:
 

package/dist/index.cjs

@@ -1593,11 +1593,14 @@ async function claim402IndexDomain(domainOrUrl, opts = {}) {
     if (!res.ok) {
       return { ok: false, domain, httpStatus: res.status, detail: _nullishCoalesce(pickString(body, "error", "detail", "message"), () => ( `402 Index claim returned HTTP ${res.status}.`)) };
     }
+    const verificationToken = pickString(body, "verification_token");
+    const verificationHash = await _asyncNullishCoalesce(pickString(body, "verification_hash"), async () => ( (verificationToken ? await sha256Hex(verificationToken) : void 0)));
     return {
       ok: true,
       domain,
       httpStatus: res.status,
-      ...optionalString("verificationHash", pickString(body, "verification_hash")),
+      ...optionalString("verificationHash", verificationHash),
+      ...optionalString("verificationToken", verificationToken),
       ...optionalString("verificationUrl", pickString(body, "verification_url")),
       ...optionalString("instructions", pickString(body, "instructions"))
     };
@@ -1605,6 +1608,10 @@ async function claim402IndexDomain(domainOrUrl, opts = {}) {
     return { ok: false, domain, detail: errMsg(err) };
   }
 }
+async function sha256Hex(input) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 async function verify402IndexDomain(domainOrUrl) {
   const domain = hostOf(domainOrUrl);
   try {
@@ -1634,6 +1641,12 @@ async function readSiwxInfo(res) {
     const ext = body.extensions;
     const siwx = _optionalChain([ext, 'optionalAccess', _8 => _8["sign-in-with-x"]]);
     const info = _nullishCoalesce(_optionalChain([siwx, 'optionalAccess', _9 => _9.info]), () => ( siwx));
+    if (info && info.chainId == null && Array.isArray(_optionalChain([siwx, 'optionalAccess', _10 => _10.supportedChains]))) {
+      const evm = siwx.supportedChains.find(
+        (c) => typeof _optionalChain([c, 'optionalAccess', _11 => _11.chainId]) === "string" && c.chainId.startsWith("eip155:")
+      );
+      if (evm && typeof evm.chainId === "string") info.chainId = evm.chainId;
+    }
     if (info && typeof info.domain === "string" && info.domain.length > 0 && typeof info.nonce === "string" && info.nonce.length > 0 && typeof info.uri === "string" && info.uri.length > 0) {
       return info;
     }
@@ -1686,7 +1699,7 @@ function mapRails(accepts) {
 }
 function matchesQuery(r, query) {
   const q = query.toLowerCase();
-  return r.resource.toLowerCase().includes(q) || (_nullishCoalesce(_optionalChain([r, 'access', _10 => _10.name, 'optionalAccess', _11 => _11.toLowerCase, 'call', _12 => _12(), 'access', _13 => _13.includes, 'call', _14 => _14(q)]), () => ( false))) || (_nullishCoalesce(_optionalChain([r, 'access', _15 => _15.description, 'optionalAccess', _16 => _16.toLowerCase, 'call', _17 => _17(), 'access', _18 => _18.includes, 'call', _19 => _19(q)]), () => ( false)));
+  return r.resource.toLowerCase().includes(q) || (_nullishCoalesce(_optionalChain([r, 'access', _12 => _12.name, 'optionalAccess', _13 => _13.toLowerCase, 'call', _14 => _14(), 'access', _15 => _15.includes, 'call', _16 => _16(q)]), () => ( false))) || (_nullishCoalesce(_optionalChain([r, 'access', _17 => _17.description, 'optionalAccess', _18 => _18.toLowerCase, 'call', _19 => _19(), 'access', _20 => _20.includes, 'call', _21 => _21(q)]), () => ( false)));
 }
 function pickString(o, ...keys) {
   for (const k of keys) {
@@ -1717,7 +1730,8 @@ function firstArray(o, ...keys) {
 }
 function hostOf(url) {
   try {
-    return new URL(url).hostname;
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
+    return new URL(withScheme).hostname || url;
   } catch (e20) {
     return url;
   }
@@ -1726,8 +1740,13 @@ function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function encodeBase642(str) {
-  if (typeof btoa === "function") return btoa(str);
   if (typeof Buffer !== "undefined") return Buffer.from(str, "utf8").toString("base64");
+  if (typeof btoa === "function" && typeof TextEncoder !== "undefined") {
+    const bytes = new TextEncoder().encode(str);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
   throw new Error("No base64 encoder available in this runtime.");
 }
 
@@ -1824,7 +1843,7 @@ var SpendLedger = (_class = class {constructor() { _class.prototype.__init.call(
   }
   /** Running total (base units) already spent on this (network, asset). */
   totalFor(network, asset) {
-    return _nullishCoalesce(_optionalChain([this, 'access', _20 => _20.buckets, 'access', _21 => _21.get, 'call', _22 => _22(keyFor(network, asset)), 'optionalAccess', _23 => _23.total]), () => ( 0n));
+    return _nullishCoalesce(_optionalChain([this, 'access', _22 => _22.buckets, 'access', _23 => _23.get, 'call', _24 => _24(keyFor(network, asset)), 'optionalAccess', _25 => _25.total]), () => ( 0n));
   }
   /** An immutable snapshot of all spend so far. */
   summary() {
@@ -1898,7 +1917,7 @@ var PipRailClient = (_class2 = class {
    * as-is) or a plain object (serialised as JSON).
    */
   post(url, body, init) {
-    const headers = new Headers(_optionalChain([init, 'optionalAccess', _24 => _24.headers]));
+    const headers = new Headers(_optionalChain([init, 'optionalAccess', _26 => _26.headers]));
     let payload;
     if (body === void 0 || body === null) {
       payload = void 0;
@@ -1929,7 +1948,7 @@ var PipRailClient = (_class2 = class {
    * "0.05 USDC on Base, within budget → pay it." No funds move.
    */
   async quote(url, init) {
-    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _25 => _25.method]), () => ( "GET")) });
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _27 => _27.method]), () => ( "GET")) });
     if (res.status !== 402) return null;
     const { quote } = await this.resolveChallenge(url, res);
     return quote;
@@ -1948,7 +1967,7 @@ var PipRailClient = (_class2 = class {
    * on Tron, where a USD₮ transfer can cost real TRX.
    */
   async estimateCost(url, init) {
-    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _26 => _26.method]), () => ( "GET")) });
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _28 => _28.method]), () => ( "GET")) });
     if (res.status !== 402) return null;
     const { net, accept, quote } = await this.resolveChallenge(url, res);
     const cost = await net.estimateCost(accept);
@@ -1979,7 +1998,7 @@ var PipRailClient = (_class2 = class {
    * the plan yourself. No funds move.
    */
   async planPayment(url, init) {
-    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _27 => _27.method]), () => ( "GET")) });
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _29 => _29.method]), () => ( "GET")) });
     if (res.status !== 402) return null;
     const challenge = await parseChallenge(res);
     if (!challenge) {
@@ -2146,7 +2165,7 @@ var PipRailClient = (_class2 = class {
    * streams throw `NonReplayableBodyError`.
    */
   async fetch(url, init) {
-    const body = _optionalChain([init, 'optionalAccess', _28 => _28.body]);
+    const body = _optionalChain([init, 'optionalAccess', _30 => _30.body]);
     if (body !== void 0 && body !== null && !isReplayableBodyInit(body)) {
       throw new (0, _chunkMDLZJGLYcjs.NonReplayableBodyError)(
         "fetch(): init.body is not replayable. Pass a string, FormData, URLSearchParams, ArrayBuffer, or Blob \u2014 not a ReadableStream."
@@ -2158,7 +2177,7 @@ var PipRailClient = (_class2 = class {
     const { net, wallet, challenge } = resolved;
     let accept = resolved.accept;
     let quote = resolved.quote;
-    const autoRoute = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'optionalAccess', _29 => _29.autoRoute]), () => ( this.opts.autoRoute)), () => ( false));
+    const autoRoute = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'optionalAccess', _31 => _31.autoRoute]), () => ( this.opts.autoRoute)), () => ( false));
     if (autoRoute) {
       const plan = await this.planFromChallenge(net, wallet, challenge, url);
       if (!plan.best) {
@@ -2320,8 +2339,8 @@ var PipRailClient = (_class2 = class {
     }
     const amountBase = BigInt(accept.amount);
     const described = net.describeAsset(accept.asset);
-    const decimals = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _30 => _30.decimals]), () => ( accept.extra.decimals));
-    const symbol = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _31 => _31.symbol]), () => ( accept.extra.symbol));
+    const decimals = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _32 => _32.decimals]), () => ( accept.extra.decimals));
+    const symbol = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _33 => _33.symbol]), () => ( accept.extra.symbol));
     const amountFormatted = _chunkMDLZJGLYcjs.formatUnits.call(void 0, amountBase, decimals);
     const intent = {
       host: hostOf2(url),
@@ -2430,7 +2449,7 @@ var PipRailClient = (_class2 = class {
       accepted: accept,
       payload: { nonce: accept.extra.nonce, txHash: ref }
     };
-    const headers = new Headers(_optionalChain([originalInit, 'optionalAccess', _32 => _32.headers]));
+    const headers = new Headers(_optionalChain([originalInit, 'optionalAccess', _34 => _34.headers]));
     headers.set(HEADER_SIGNATURE, buildSignatureHeader(signature));
     let lastResponse = null;
     let lastReason = null;
@@ -2445,7 +2464,7 @@ var PipRailClient = (_class2 = class {
         () => timeoutController.abort(),
         this.retryTimeoutMs
       );
-      const signal = _optionalChain([originalInit, 'optionalAccess', _33 => _33.signal]) && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, originalInit.signal]) : timeoutController.signal;
+      const signal = _optionalChain([originalInit, 'optionalAccess', _35 => _35.signal]) && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, originalInit.signal]) : timeoutController.signal;
       try {
         lastResponse = await fetch(url, {
           ..._nullishCoalesce(originalInit, () => ( {})),
@@ -2518,10 +2537,10 @@ function buildFundingHint(options, chainLabel) {
     return `Couldn't fully read your wallet on ${chainLabel} (RPC throttled) \u2014 retry; you may already be able to pay ${target.quote.amountFormatted} ${sym}.`;
   }
   const parts = [];
-  if (target.blockers.includes("INSUFFICIENT_TOKEN") && _optionalChain([target, 'access', _34 => _34.shortfall, 'optionalAccess', _35 => _35.token])) {
+  if (target.blockers.includes("INSUFFICIENT_TOKEN") && _optionalChain([target, 'access', _36 => _36.shortfall, 'optionalAccess', _37 => _37.token])) {
     parts.push(`top up ${target.shortfall.token} ${sym}`);
   }
-  if (target.blockers.includes("INSUFFICIENT_GAS") && _optionalChain([target, 'access', _36 => _36.shortfall, 'optionalAccess', _37 => _37.native])) {
+  if (target.blockers.includes("INSUFFICIENT_GAS") && _optionalChain([target, 'access', _38 => _38.shortfall, 'optionalAccess', _39 => _39.native])) {
     parts.push(`add ~${target.shortfall.native} ${target.cost.feeSymbol} for gas`);
   }
   return parts.length ? `Can't settle on ${chainLabel}: ${parts.join(" and ")} (to pay ${target.quote.amountFormatted} ${sym}).` : `Can't settle on ${chainLabel} for ${target.quote.amountFormatted} ${sym}.`;
@@ -2535,7 +2554,7 @@ async function planAcross(clients, url, init) {
   const status = best ? "ready" : options.some((o) => o.state === "unknown") ? "unknown" : "blocked";
   return {
     url,
-    network: _nullishCoalesce(_optionalChain([best, 'optionalAccess', _38 => _38.accept, 'access', _39 => _39.network]), () => ( live[0].network)),
+    network: _nullishCoalesce(_optionalChain([best, 'optionalAccess', _40 => _40.accept, 'access', _41 => _41.network]), () => ( live[0].network)),
     status,
     payable: best !== null,
     best,
@@ -2568,8 +2587,8 @@ function isReplayableBodyInit(value) {
 async function readInvalidReason(response) {
   try {
     const body = await response.clone().json();
-    const ext = _optionalChain([body, 'optionalAccess', _40 => _40.extensions]);
-    const piprail = _optionalChain([ext, 'optionalAccess', _41 => _41.piprail]);
+    const ext = _optionalChain([body, 'optionalAccess', _42 => _42.extensions]);
+    const piprail = _optionalChain([ext, 'optionalAccess', _43 => _43.piprail]);
     if (piprail && typeof piprail.code === "string") {
       return {
         error: piprail.code,
@@ -2773,7 +2792,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_register",
-      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted. NOTE: index/agent payers are overwhelmingly standard `exact` clients \u2014 a default onchain-proof-only gate gets listed but they cannot pay it, so add an `exact` rail (and set the gate's `discovery` option, required for x402scan) to be usefully discoverable AND payable.",
       annotations: {
         title: "Register an x402 endpoint",
         readOnlyHint: false,
@@ -2807,6 +2826,87 @@ function paymentTools(client) {
   ];
 }
 
+// src/discovery.ts
+var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
+function buildBazaarExtension(descriptor = {}) {
+  const method = (_nullishCoalesce(descriptor.method, () => ( "GET"))).toUpperCase();
+  const queryParams = _nullishCoalesce(descriptor.queryParams, () => ( {}));
+  return {
+    info: {
+      input: { type: "http", method, queryParams },
+      output: _nullishCoalesce(descriptor.output, () => ( { type: "json" }))
+    },
+    schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      properties: {
+        input: {
+          type: "object",
+          properties: {
+            type: { type: "string", const: "http" },
+            method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"] },
+            queryParams: { type: "object", properties: queryParams, additionalProperties: false }
+          },
+          required: ["type", "method"],
+          additionalProperties: false
+        }
+      },
+      required: ["input"]
+    }
+  };
+}
+function pathOf(url) {
+  try {
+    return new URL(url).pathname || "/";
+  } catch (e26) {
+    return url.startsWith("/") ? url : `/${url}`;
+  }
+}
+function buildOpenApi(input) {
+  const paths = {};
+  for (const r of input.resources) {
+    const path = pathOf(r.url);
+    const method = (_nullishCoalesce(r.method, () => ( "GET"))).toLowerCase();
+    const op = {
+      ...r.description ? { summary: r.description } : {},
+      responses: {
+        "200": { description: "Paid \u2014 the resource." },
+        "402": { description: "Payment required (x402)." }
+      },
+      "x-payment-info": {
+        x402Version: 2,
+        accepts: r.accepts
+      }
+    };
+    paths[path] = { ..._nullishCoalesce(paths[path], () => ( {})), [method]: op };
+  }
+  return {
+    openapi: "3.1.0",
+    info: { title: _nullishCoalesce(input.title, () => ( "PipRail x402 resources")), version: _nullishCoalesce(input.version, () => ( "1.0.0")) },
+    servers: [{ url: input.origin }],
+    paths,
+    // "Built with @piprail/sdk" — default on (opt out with attribution:false). At the
+    // document ROOT so `info` stays exactly { title, version }.
+    ...input.attribution === false ? {} : { "x-generator": GENERATOR },
+    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { "x-agentcash-provenance": { ownershipProofs: input.ownershipProofs } } : {}
+  };
+}
+function buildWellKnownX402(input) {
+  return {
+    version: 1,
+    resources: input.resources.map((r) => r.url),
+    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
+  };
+}
+function buildX402DnsTxt(input) {
+  const descriptor = input.descriptor ? `descriptor=${input.descriptor};` : "";
+  return {
+    name: `_x402.${input.host}`,
+    type: "TXT",
+    value: `v=x4021;${descriptor}url=${input.discoveryUrl}`
+  };
+}
+
 // src/facilitator.ts
 function safeStringify(value) {
   return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
@@ -2831,7 +2931,7 @@ async function post(url, body, headers) {
   let json = null;
   try {
     json = await res.json();
-  } catch (e26) {
+  } catch (e27) {
   }
   return { status: res.status, json };
 }
@@ -3055,6 +3155,8 @@ function createPaymentGate(options) {
   async function makeChallenge(resourceUrl, opts) {
     const specs = await ready();
     const nonce = genNonce();
+    const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
+    const extensions = { ...bazaar, ..._optionalChain([opts, 'optionalAccess', _44 => _44.extensions]) };
     const challenge2 = {
       x402Version: 2,
       resource: {
@@ -3062,8 +3164,8 @@ function createPaymentGate(options) {
         ...options.description ? { description: options.description } : {}
       },
       accepts: buildAccepts(specs, nonce),
-      ..._optionalChain([opts, 'optionalAccess', _42 => _42.error]) ? { error: opts.error } : {},
-      ..._optionalChain([opts, 'optionalAccess', _43 => _43.extensions]) ? { extensions: opts.extensions } : {}
+      ..._optionalChain([opts, 'optionalAccess', _45 => _45.error]) ? { error: opts.error } : {},
+      ...Object.keys(extensions).length > 0 ? { extensions } : {}
     };
     return { challenge: challenge2, requiredHeader: buildChallengeHeader(challenge2) };
   }
@@ -3085,7 +3187,7 @@ function createPaymentGate(options) {
     if (options.onPaid) {
       try {
         options.onPaid(receipt);
-      } catch (e27) {
+      } catch (e28) {
       }
     }
   }
@@ -3250,60 +3352,6 @@ function normaliseHeader(value) {
   return value;
 }
 
-// src/discovery.ts
-var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
-function pathOf(url) {
-  try {
-    return new URL(url).pathname || "/";
-  } catch (e28) {
-    return url.startsWith("/") ? url : `/${url}`;
-  }
-}
-function buildOpenApi(input) {
-  const paths = {};
-  for (const r of input.resources) {
-    const path = pathOf(r.url);
-    const method = (_nullishCoalesce(r.method, () => ( "GET"))).toLowerCase();
-    const op = {
-      ...r.description ? { summary: r.description } : {},
-      responses: {
-        "200": { description: "Paid \u2014 the resource." },
-        "402": { description: "Payment required (x402)." }
-      },
-      "x-payment-info": {
-        x402Version: 2,
-        accepts: r.accepts,
-        bazaar: { discoverable: true }
-      }
-    };
-    paths[path] = { ..._nullishCoalesce(paths[path], () => ( {})), [method]: op };
-  }
-  return {
-    openapi: "3.1.0",
-    info: { title: _nullishCoalesce(input.title, () => ( "PipRail x402 resources")), version: _nullishCoalesce(input.version, () => ( "1.0.0")) },
-    servers: [{ url: input.origin }],
-    paths,
-    // "Built with @piprail/sdk" — default on (opt out with attribution:false). At the
-    // document ROOT so `info` stays exactly { title, version }.
-    ...input.attribution === false ? {} : { "x-generator": GENERATOR },
-    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { "x-agentcash-provenance": { ownershipProofs: input.ownershipProofs } } : {}
-  };
-}
-function buildWellKnownX402(input) {
-  return {
-    version: 1,
-    resources: input.resources.map((r) => r.url),
-    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
-  };
-}
-function buildX402DnsTxt(input) {
-  const descriptor = input.descriptor ? `descriptor=${input.descriptor};` : "";
-  return {
-    name: `_x402.${input.host}`,
-    type: "TXT",
-    value: `v=x4021;${descriptor}url=${input.discoveryUrl}`
-  };
-}
 
 
 
@@ -3367,4 +3415,4 @@ function buildX402DnsTxt(input) {
 
 
 
-exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkMDLZJGLYcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkMDLZJGLYcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkMDLZJGLYcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkMDLZJGLYcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkMDLZJGLYcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkMDLZJGLYcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkMDLZJGLYcjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkMDLZJGLYcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkMDLZJGLYcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkMDLZJGLYcjs.PipRailError; exports.RecipientNotReadyError = _chunkMDLZJGLYcjs.RecipientNotReadyError; exports.SettlementError = _chunkMDLZJGLYcjs.SettlementError; exports.UnknownTokenError = _chunkMDLZJGLYcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkMDLZJGLYcjs.UnsupportedNetworkError; exports.WrongChainError = _chunkMDLZJGLYcjs.WrongChainError; exports.WrongFamilyError = _chunkMDLZJGLYcjs.WrongFamilyError; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.getDirectoryInfo = getDirectoryInfo; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.toInsufficientFundsError = _chunkMDLZJGLYcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;
+exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkMDLZJGLYcjs.ConfirmationTimeoutError; exports.DIRECTORY_INFO = DIRECTORY_INFO; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.HEADER_REQUIRED = HEADER_REQUIRED; exports.HEADER_RESPONSE = HEADER_RESPONSE; exports.HEADER_RESPONSE_V1 = HEADER_RESPONSE_V1; exports.HEADER_SIGNATURE = HEADER_SIGNATURE; exports.HEADER_SIGNATURE_V1 = HEADER_SIGNATURE_V1; exports.InsufficientFundsError = _chunkMDLZJGLYcjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkMDLZJGLYcjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkMDLZJGLYcjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkMDLZJGLYcjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkMDLZJGLYcjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkMDLZJGLYcjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkMDLZJGLYcjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkMDLZJGLYcjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkMDLZJGLYcjs.PipRailError; exports.RecipientNotReadyError = _chunkMDLZJGLYcjs.RecipientNotReadyError; exports.SettlementError = _chunkMDLZJGLYcjs.SettlementError; exports.UnknownTokenError = _chunkMDLZJGLYcjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkMDLZJGLYcjs.UnsupportedNetworkError; exports.WrongChainError = _chunkMDLZJGLYcjs.WrongChainError; exports.WrongFamilyError = _chunkMDLZJGLYcjs.WrongFamilyError; exports.buildBazaarExtension = buildBazaarExtension; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildOpenApi = buildOpenApi; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.buildWellKnownX402 = buildWellKnownX402; exports.buildX402DnsTxt = buildX402DnsTxt; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.claim402IndexDomain = claim402IndexDomain; exports.createPaymentGate = createPaymentGate; exports.decorateOutcome = decorateOutcome; exports.eip3009Abi = eip3009Abi; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.getDirectoryInfo = getDirectoryInfo; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactPaymentHeader = parseExactPaymentHeader; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.readExactDomain = readExactDomain; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.settleViaFacilitator = settleViaFacilitator; exports.toInsufficientFundsError = _chunkMDLZJGLYcjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody; exports.verify402IndexDomain = verify402IndexDomain;

package/dist/index.d.cts

@@ -4370,9 +4370,14 @@ declare function registerX402Scan(input: {
 interface DomainClaim {
     ok: boolean;
     domain: string;
-    /** Serve THIS string as the entire body of `verificationUrl`. */
+    /** The exact text to serve as the ENTIRE body of `verificationUrl` — this is what
+     *  402 Index fetches and checks (the SHA-256 of the token). Always populated on
+     *  success: read from the response, or computed as `sha256(verificationToken)` if
+     *  the API returns only the token. Serve THIS. */
     verificationHash?: string;
-    /** Where to serve it — your `https://<domain>/.well-known/402index-verify.txt`. */
+    /** The raw 64-hex token 402 Index issued (the preimage of `verificationHash`). */
+    verificationToken?: string;
+    /** Where to serve `verificationHash` — your `https://<domain>/.well-known/402index-verify.txt`. */
     verificationUrl?: string;
     /** 402 Index's own human instructions. */
     instructions?: string;
@@ -5129,10 +5134,6 @@ interface OpenApiOperation {
     'x-payment-info': {
         x402Version: 2;
         accepts: PaymentRail[];
-        /** Bazaar-style input schema marker so a strict index doesn't "skip" the op. */
-        bazaar: {
-            discoverable: true;
-        };
     };
 }
 /** x402scan's legacy origin file (`/.well-known/x402`). */
@@ -5141,6 +5142,46 @@ interface WellKnownX402 {
     resources: string[];
     ownershipProofs?: string[];
 }
+/**
+ * Describes a resource's INPUT for discovery. The open indexes that REQUIRE an
+ * input schema (x402scan rejects a listing without one) read this from a
+ * `extensions.bazaar` block. Pass it to a gate's `discovery` option (emits the
+ * block in the 402 challenge) or build it directly with {@link buildBazaarExtension}.
+ */
+interface DiscoveryDescriptor {
+    /** HTTP method the resource answers. Default `'GET'`. */
+    method?: string;
+    /** Query params the resource reads, as a JSON-Schema `properties` object
+     *  (name → schema). Default `{}` — a no-input GET. */
+    queryParams?: Record<string, unknown>;
+    /** Optional output hint (shape/example) for a richer listing. */
+    output?: {
+        type?: string;
+        example?: unknown;
+    };
+}
+/** The `extensions.bazaar` discovery block (the x402 "bazaar" convention the open
+ *  indexes parse: `info.input` describes the request, `schema` is its JSON Schema). */
+interface BazaarExtension {
+    info: {
+        input: {
+            type: 'http';
+            method: string;
+            queryParams: Record<string, unknown>;
+        };
+        output?: {
+            type?: string;
+            example?: unknown;
+        };
+    };
+    schema: Record<string, unknown>;
+}
+/**
+ * Build the `extensions.bazaar` block that satisfies x402scan's mandatory input-schema
+ * check, from a {@link DiscoveryDescriptor}. Pure. Defaults to a no-input GET — the
+ * minimal shape a live x402scan listing accepts.
+ */
+declare function buildBazaarExtension(descriptor?: DiscoveryDescriptor): BazaarExtension;
 /** The `_x402` DNS TXT pointer record (experimental draft). */
 interface X402DnsRecord {
     name: string;
@@ -5292,6 +5333,14 @@ interface RequirePaymentOptions {
      * Omit to keep the gate exactly as today (`onchain-proof` only).
      */
     exact?: ExactRailOption;
+    /**
+     * Make this gate's 402 self-describing for the open indexes — **x402scan REQUIRES
+     * an input schema or it won't list the resource.** Set `true` for a no-input GET,
+     * or pass a {@link DiscoveryDescriptor} to describe the request. Emits an
+     * `extensions.bazaar` block in the 402 challenge. Opt-in; omitting it leaves the
+     * challenge byte-identical to before.
+     */
+    discovery?: boolean | DiscoveryDescriptor;
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -5898,4 +5947,4 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
     version: string;
 } | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -4370,9 +4370,14 @@ declare function registerX402Scan(input: {
 interface DomainClaim {
     ok: boolean;
     domain: string;
-    /** Serve THIS string as the entire body of `verificationUrl`. */
+    /** The exact text to serve as the ENTIRE body of `verificationUrl` — this is what
+     *  402 Index fetches and checks (the SHA-256 of the token). Always populated on
+     *  success: read from the response, or computed as `sha256(verificationToken)` if
+     *  the API returns only the token. Serve THIS. */
     verificationHash?: string;
-    /** Where to serve it — your `https://<domain>/.well-known/402index-verify.txt`. */
+    /** The raw 64-hex token 402 Index issued (the preimage of `verificationHash`). */
+    verificationToken?: string;
+    /** Where to serve `verificationHash` — your `https://<domain>/.well-known/402index-verify.txt`. */
     verificationUrl?: string;
     /** 402 Index's own human instructions. */
     instructions?: string;
@@ -5129,10 +5134,6 @@ interface OpenApiOperation {
     'x-payment-info': {
         x402Version: 2;
         accepts: PaymentRail[];
-        /** Bazaar-style input schema marker so a strict index doesn't "skip" the op. */
-        bazaar: {
-            discoverable: true;
-        };
     };
 }
 /** x402scan's legacy origin file (`/.well-known/x402`). */
@@ -5141,6 +5142,46 @@ interface WellKnownX402 {
     resources: string[];
     ownershipProofs?: string[];
 }
+/**
+ * Describes a resource's INPUT for discovery. The open indexes that REQUIRE an
+ * input schema (x402scan rejects a listing without one) read this from a
+ * `extensions.bazaar` block. Pass it to a gate's `discovery` option (emits the
+ * block in the 402 challenge) or build it directly with {@link buildBazaarExtension}.
+ */
+interface DiscoveryDescriptor {
+    /** HTTP method the resource answers. Default `'GET'`. */
+    method?: string;
+    /** Query params the resource reads, as a JSON-Schema `properties` object
+     *  (name → schema). Default `{}` — a no-input GET. */
+    queryParams?: Record<string, unknown>;
+    /** Optional output hint (shape/example) for a richer listing. */
+    output?: {
+        type?: string;
+        example?: unknown;
+    };
+}
+/** The `extensions.bazaar` discovery block (the x402 "bazaar" convention the open
+ *  indexes parse: `info.input` describes the request, `schema` is its JSON Schema). */
+interface BazaarExtension {
+    info: {
+        input: {
+            type: 'http';
+            method: string;
+            queryParams: Record<string, unknown>;
+        };
+        output?: {
+            type?: string;
+            example?: unknown;
+        };
+    };
+    schema: Record<string, unknown>;
+}
+/**
+ * Build the `extensions.bazaar` block that satisfies x402scan's mandatory input-schema
+ * check, from a {@link DiscoveryDescriptor}. Pure. Defaults to a no-input GET — the
+ * minimal shape a live x402scan listing accepts.
+ */
+declare function buildBazaarExtension(descriptor?: DiscoveryDescriptor): BazaarExtension;
 /** The `_x402` DNS TXT pointer record (experimental draft). */
 interface X402DnsRecord {
     name: string;
@@ -5292,6 +5333,14 @@ interface RequirePaymentOptions {
      * Omit to keep the gate exactly as today (`onchain-proof` only).
      */
     exact?: ExactRailOption;
+    /**
+     * Make this gate's 402 self-describing for the open indexes — **x402scan REQUIRES
+     * an input schema or it won't list the resource.** Set `true` for a no-input GET,
+     * or pass a {@link DiscoveryDescriptor} to describe the request. Emits an
+     * `extensions.bazaar` block in the 402 challenge. Opt-in; omitting it leaves the
+     * challenge byte-identical to before.
+     */
+    discovery?: boolean | DiscoveryDescriptor;
 }
 type VerifyPaymentResult = {
     kind: 'paid';
@@ -5898,4 +5947,4 @@ declare function readExactDomain(publicClient: PublicClient, asset: string): Pro
     version: string;
 } | null>;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildBazaarExtension, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, createPaymentGate, decorateOutcome, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, getDirectoryInfo, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, readExactDomain, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, settleViaFacilitator, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.js

@@ -1593,11 +1593,14 @@ async function claim402IndexDomain(domainOrUrl, opts = {}) {
     if (!res.ok) {
       return { ok: false, domain, httpStatus: res.status, detail: pickString(body, "error", "detail", "message") ?? `402 Index claim returned HTTP ${res.status}.` };
     }
+    const verificationToken = pickString(body, "verification_token");
+    const verificationHash = pickString(body, "verification_hash") ?? (verificationToken ? await sha256Hex(verificationToken) : void 0);
     return {
       ok: true,
       domain,
       httpStatus: res.status,
-      ...optionalString("verificationHash", pickString(body, "verification_hash")),
+      ...optionalString("verificationHash", verificationHash),
+      ...optionalString("verificationToken", verificationToken),
       ...optionalString("verificationUrl", pickString(body, "verification_url")),
       ...optionalString("instructions", pickString(body, "instructions"))
     };
@@ -1605,6 +1608,10 @@ async function claim402IndexDomain(domainOrUrl, opts = {}) {
     return { ok: false, domain, detail: errMsg(err) };
   }
 }
+async function sha256Hex(input) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 async function verify402IndexDomain(domainOrUrl) {
   const domain = hostOf(domainOrUrl);
   try {
@@ -1634,6 +1641,12 @@ async function readSiwxInfo(res) {
     const ext = body.extensions;
     const siwx = ext?.["sign-in-with-x"];
     const info = siwx?.info ?? siwx;
+    if (info && info.chainId == null && Array.isArray(siwx?.supportedChains)) {
+      const evm = siwx.supportedChains.find(
+        (c) => typeof c?.chainId === "string" && c.chainId.startsWith("eip155:")
+      );
+      if (evm && typeof evm.chainId === "string") info.chainId = evm.chainId;
+    }
     if (info && typeof info.domain === "string" && info.domain.length > 0 && typeof info.nonce === "string" && info.nonce.length > 0 && typeof info.uri === "string" && info.uri.length > 0) {
       return info;
     }
@@ -1717,7 +1730,8 @@ function firstArray(o, ...keys) {
 }
 function hostOf(url) {
   try {
-    return new URL(url).hostname;
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(url) ? url : `https://${url}`;
+    return new URL(withScheme).hostname || url;
   } catch {
     return url;
   }
@@ -1726,8 +1740,13 @@ function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function encodeBase642(str) {
-  if (typeof btoa === "function") return btoa(str);
   if (typeof Buffer !== "undefined") return Buffer.from(str, "utf8").toString("base64");
+  if (typeof btoa === "function" && typeof TextEncoder !== "undefined") {
+    const bytes = new TextEncoder().encode(str);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+  }
   throw new Error("No base64 encoder available in this runtime.");
 }
 
@@ -2773,7 +2792,7 @@ function paymentTools(client) {
     },
     {
       name: "piprail_register",
-      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; a self-registered listing is pending review (verify your domain on 402index.io for instant approval). Returns one outcome per index ({ source, ok, detail, visibility, note }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted. NOTE: index/agent payers are overwhelmingly standard `exact` clients \u2014 a default onchain-proof-only gate gets listed but they cannot pay it, so add an `exact` rail (and set the gate's `discovery` option, required for x402scan) to be usefully discoverable AND payable.",
       annotations: {
         title: "Register an x402 endpoint",
         readOnlyHint: false,
@@ -2807,6 +2826,87 @@ function paymentTools(client) {
   ];
 }
 
+// src/discovery.ts
+var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
+function buildBazaarExtension(descriptor = {}) {
+  const method = (descriptor.method ?? "GET").toUpperCase();
+  const queryParams = descriptor.queryParams ?? {};
+  return {
+    info: {
+      input: { type: "http", method, queryParams },
+      output: descriptor.output ?? { type: "json" }
+    },
+    schema: {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      properties: {
+        input: {
+          type: "object",
+          properties: {
+            type: { type: "string", const: "http" },
+            method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"] },
+            queryParams: { type: "object", properties: queryParams, additionalProperties: false }
+          },
+          required: ["type", "method"],
+          additionalProperties: false
+        }
+      },
+      required: ["input"]
+    }
+  };
+}
+function pathOf(url) {
+  try {
+    return new URL(url).pathname || "/";
+  } catch {
+    return url.startsWith("/") ? url : `/${url}`;
+  }
+}
+function buildOpenApi(input) {
+  const paths = {};
+  for (const r of input.resources) {
+    const path = pathOf(r.url);
+    const method = (r.method ?? "GET").toLowerCase();
+    const op = {
+      ...r.description ? { summary: r.description } : {},
+      responses: {
+        "200": { description: "Paid \u2014 the resource." },
+        "402": { description: "Payment required (x402)." }
+      },
+      "x-payment-info": {
+        x402Version: 2,
+        accepts: r.accepts
+      }
+    };
+    paths[path] = { ...paths[path] ?? {}, [method]: op };
+  }
+  return {
+    openapi: "3.1.0",
+    info: { title: input.title ?? "PipRail x402 resources", version: input.version ?? "1.0.0" },
+    servers: [{ url: input.origin }],
+    paths,
+    // "Built with @piprail/sdk" — default on (opt out with attribution:false). At the
+    // document ROOT so `info` stays exactly { title, version }.
+    ...input.attribution === false ? {} : { "x-generator": GENERATOR },
+    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { "x-agentcash-provenance": { ownershipProofs: input.ownershipProofs } } : {}
+  };
+}
+function buildWellKnownX402(input) {
+  return {
+    version: 1,
+    resources: input.resources.map((r) => r.url),
+    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
+  };
+}
+function buildX402DnsTxt(input) {
+  const descriptor = input.descriptor ? `descriptor=${input.descriptor};` : "";
+  return {
+    name: `_x402.${input.host}`,
+    type: "TXT",
+    value: `v=x4021;${descriptor}url=${input.discoveryUrl}`
+  };
+}
+
 // src/facilitator.ts
 function safeStringify(value) {
   return JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
@@ -3055,6 +3155,8 @@ function createPaymentGate(options) {
   async function makeChallenge(resourceUrl, opts) {
     const specs = await ready();
     const nonce = genNonce();
+    const bazaar = options.discovery ? { bazaar: buildBazaarExtension(options.discovery === true ? {} : options.discovery) } : void 0;
+    const extensions = { ...bazaar, ...opts?.extensions };
     const challenge2 = {
       x402Version: 2,
       resource: {
@@ -3063,7 +3165,7 @@ function createPaymentGate(options) {
       },
       accepts: buildAccepts(specs, nonce),
       ...opts?.error ? { error: opts.error } : {},
-      ...opts?.extensions ? { extensions: opts.extensions } : {}
+      ...Object.keys(extensions).length > 0 ? { extensions } : {}
     };
     return { challenge: challenge2, requiredHeader: buildChallengeHeader(challenge2) };
   }
@@ -3249,61 +3351,6 @@ function normaliseHeader(value) {
   if (Array.isArray(value)) return value[0];
   return value;
 }
-
-// src/discovery.ts
-var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
-function pathOf(url) {
-  try {
-    return new URL(url).pathname || "/";
-  } catch {
-    return url.startsWith("/") ? url : `/${url}`;
-  }
-}
-function buildOpenApi(input) {
-  const paths = {};
-  for (const r of input.resources) {
-    const path = pathOf(r.url);
-    const method = (r.method ?? "GET").toLowerCase();
-    const op = {
-      ...r.description ? { summary: r.description } : {},
-      responses: {
-        "200": { description: "Paid \u2014 the resource." },
-        "402": { description: "Payment required (x402)." }
-      },
-      "x-payment-info": {
-        x402Version: 2,
-        accepts: r.accepts,
-        bazaar: { discoverable: true }
-      }
-    };
-    paths[path] = { ...paths[path] ?? {}, [method]: op };
-  }
-  return {
-    openapi: "3.1.0",
-    info: { title: input.title ?? "PipRail x402 resources", version: input.version ?? "1.0.0" },
-    servers: [{ url: input.origin }],
-    paths,
-    // "Built with @piprail/sdk" — default on (opt out with attribution:false). At the
-    // document ROOT so `info` stays exactly { title, version }.
-    ...input.attribution === false ? {} : { "x-generator": GENERATOR },
-    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { "x-agentcash-provenance": { ownershipProofs: input.ownershipProofs } } : {}
-  };
-}
-function buildWellKnownX402(input) {
-  return {
-    version: 1,
-    resources: input.resources.map((r) => r.url),
-    ...input.ownershipProofs && input.ownershipProofs.length > 0 ? { ownershipProofs: input.ownershipProofs } : {}
-  };
-}
-function buildX402DnsTxt(input) {
-  const descriptor = input.descriptor ? `descriptor=${input.descriptor};` : "";
-  return {
-    name: `_x402.${input.host}`,
-    type: "TXT",
-    value: `v=x4021;${descriptor}url=${input.discoveryUrl}`
-  };
-}
 export {
   CHAINS,
   ConfirmationTimeoutError,
@@ -3332,6 +3379,7 @@ export {
   UnsupportedNetworkError,
   WrongChainError,
   WrongFamilyError,
+  buildBazaarExtension,
   buildChallengeHeader,
   buildExactAuthorization,
   buildOpenApi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",