@piprail/sdk 1.6.0 → 1.8.0

package/dist/index.cjs

@@ -737,6 +737,17 @@ function makeEvmNetwork(resolved) {
     async recipientReady() {
       return { ready: "n/a" };
     },
+    // Discovery only (ownership proofs / SIWX) — never the payment path. Signs
+    // through the wallet client so it works for both { privateKey } (local) and
+    // bring-your-own { walletClient } (JSON-RPC) accounts. eip191 → recoverable
+    // with viem's recoverMessageAddress (how x402scan verifies origin ownership).
+    discoverySigner(wallet) {
+      const a = wallet._native;
+      return {
+        address: a.account.address,
+        signMessage: (message) => a.walletClient.signMessage({ account: a.account, message })
+      };
+    },
     async verify(ref, accept) {
       return verifyEvm({
         publicClient,
@@ -888,6 +899,334 @@ async function resolveNetwork2(opts) {
   return resolveNetwork(opts);
 }
 
+// src/indexes.ts
+var BAZAAR_URL = "https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources";
+var INDEX402_SEARCH = "https://402index.io/api/v1/services";
+var INDEX402_REGISTER = "https://402index.io/api/v1/register";
+var X402SCAN_REGISTER = "https://www.x402scan.com/api/x402/registry/register";
+var USER_AGENT = "@piprail/sdk (+https://piprail.com)";
+function clientHeaders(extra = {}) {
+  return { "user-agent": USER_AGENT, ...extra };
+}
+var SLUG_TO_CAIP2 = {
+  // EVM (the common index-reported slugs; others fall through to net.supports)
+  ethereum: "eip155:1",
+  base: "eip155:8453",
+  polygon: "eip155:137",
+  arbitrum: "eip155:42161",
+  optimism: "eip155:10",
+  avalanche: "eip155:43114",
+  bnb: "eip155:56",
+  bsc: "eip155:56",
+  // non-EVM families — values mirror each driver's bound caip2 exactly
+  solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  ton: "ton:-239",
+  tron: "tron:mainnet",
+  near: "near:mainnet",
+  sui: "sui:mainnet",
+  aptos: "aptos:1",
+  algorand: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k",
+  stellar: "stellar:pubnet",
+  xrpl: "xrpl:0"
+};
+function normalizeNetwork(network) {
+  if (network.includes(":")) return network;
+  return _nullishCoalesce(SLUG_TO_CAIP2[network.toLowerCase()], () => ( network));
+}
+async function searchOpenIndexes(opts = {}) {
+  const sources = _nullishCoalesce(opts.sources, () => ( ["bazaar", "402index"]));
+  const limit = _nullishCoalesce(opts.limit, () => ( 20));
+  const results = await Promise.all(
+    sources.map((source) => {
+      if (source === "bazaar") return safeSearch(() => searchBazaar(opts.query, limit, opts.signal));
+      if (source === "402index") return safeSearch(() => search402Index(opts.query, limit, opts.signal));
+      return Promise.resolve([]);
+    })
+  );
+  return dedupeByResource(results.flat());
+}
+async function safeSearch(run) {
+  try {
+    return await run();
+  } catch (e12) {
+    return [];
+  }
+}
+function dedupeByResource(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const it of items) {
+    const key = it.resource;
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(it);
+  }
+  return out;
+}
+async function searchBazaar(query, limit, signal) {
+  const res = await fetch(`${BAZAAR_URL}?limit=${encodeURIComponent(String(limit))}`, {
+    headers: clientHeaders({ accept: "application/json" }),
+    ...signal ? { signal } : {}
+  });
+  if (!res.ok) return [];
+  const body = await res.json();
+  const items = Array.isArray(body.items) ? body.items : [];
+  const mapped = items.map(mapBazaarItem).filter((r) => r !== null);
+  return query ? mapped.filter((r) => matchesQuery(r, query)) : mapped;
+}
+function mapBazaarItem(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  const resource = pickString(o, "resource", "url", "endpoint");
+  if (!resource) return null;
+  const meta = o.metadata && typeof o.metadata === "object" ? o.metadata : {};
+  return {
+    resource,
+    source: "bazaar",
+    rails: mapRails(o.accepts),
+    ...optionalString("name", pickString(meta, "name", "title")),
+    ...optionalString("description", _nullishCoalesce(pickString(meta, "description"), () => ( pickString(o, "description")))),
+    ...optionalString("category", pickString(meta, "category"))
+  };
+}
+async function search402Index(query, limit, signal) {
+  const qs = new URLSearchParams({ limit: String(limit) });
+  if (query) qs.set("q", query);
+  const res = await fetch(`${INDEX402_SEARCH}?${qs.toString()}`, {
+    headers: clientHeaders({ accept: "application/json" }),
+    ...signal ? { signal } : {}
+  });
+  if (!res.ok) return [];
+  const body = await res.json();
+  const list = firstArray(body, "services", "results", "items", "data");
+  return list.map(map402IndexItem).filter((r) => r !== null).filter((r) => r.rails.length > 0);
+}
+function map402IndexItem(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  const resource = pickString(o, "url", "resource", "endpoint");
+  if (!resource) return null;
+  const protocol = (_nullishCoalesce(pickString(o, "protocol"), () => ( "x402"))).toLowerCase();
+  if (protocol !== "x402") return null;
+  const rails = Array.isArray(o.accepts) ? mapRails(o.accepts) : railFrom402IndexFields(o);
+  const priceUsd = pickNumber(o, "price_usd", "priceUsd", "price");
+  return {
+    resource,
+    source: "402index",
+    rails,
+    ...priceUsd !== void 0 ? { priceUsd } : {},
+    ...optionalString("name", pickString(o, "name", "title")),
+    ...optionalString("description", pickString(o, "description")),
+    ...optionalString("category", pickString(o, "category", "tag"))
+  };
+}
+function railFrom402IndexFields(o) {
+  const network = pickString(o, "payment_network", "network");
+  const asset = pickString(o, "payment_asset", "asset", "token");
+  if (!network && !asset) return [];
+  return [
+    {
+      scheme: "exact",
+      network: _nullishCoalesce(network, () => ( "unknown")),
+      ...asset ? { asset } : {},
+      ...optionalString("symbol", asset)
+    }
+  ];
+}
+async function register402Index(input) {
+  try {
+    const payload = {
+      url: input.url,
+      name: _nullishCoalesce(input.name, () => ( hostOf(input.url))),
+      protocol: "x402",
+      ...input.description ? { description: input.description } : {},
+      ...typeof input.priceUsd === "number" ? { price_usd: input.priceUsd } : {},
+      ...input.asset ? { payment_asset: input.asset } : {},
+      ...input.network ? { payment_network: input.network } : {},
+      ...input.method ? { http_method: input.method.toUpperCase() } : {},
+      ...input.attribution ? { via: "@piprail/sdk" } : {}
+    };
+    const res = await fetch(INDEX402_REGISTER, {
+      method: "POST",
+      headers: clientHeaders({ "content-type": "application/json", accept: "application/json" }),
+      body: JSON.stringify(payload)
+    });
+    if (res.ok) {
+      return { source: "402index", ok: true, status: res.status, detail: "Listed on 402 Index (searchable at 402index.io)." };
+    }
+    const why = await readIndexError(res);
+    return {
+      source: "402index",
+      ok: false,
+      status: res.status,
+      detail: why ? `402 Index rejected it (HTTP ${res.status}): ${why}` : `402 Index returned HTTP ${res.status}.`
+    };
+  } catch (err) {
+    return { source: "402index", ok: false, detail: errMsg(err) };
+  }
+}
+async function readIndexError(res) {
+  try {
+    const body = await res.json();
+    const parts = [body.error, body.detail, body.message].filter(
+      (p) => typeof p === "string" && p.length > 0
+    );
+    return parts.length ? [...new Set(parts)].join(" \u2014 ") : void 0;
+  } catch (e13) {
+    return void 0;
+  }
+}
+async function registerX402Scan(input, signer) {
+  try {
+    const challengeRes = await fetch(X402SCAN_REGISTER, {
+      method: "POST",
+      headers: clientHeaders({ "content-type": "application/json", accept: "application/json" }),
+      body: JSON.stringify({ url: input.url })
+    });
+    if (challengeRes.status !== 402) {
+      return {
+        source: "x402scan",
+        ok: challengeRes.ok,
+        status: challengeRes.status,
+        detail: challengeRes.ok ? "Listed on x402scan." : `x402scan returned HTTP ${challengeRes.status} (expected a SIWX 402 challenge).`
+      };
+    }
+    const info = await readSiwxInfo(challengeRes);
+    if (!info) {
+      return { source: "x402scan", ok: false, status: 402, detail: "x402scan SIWX challenge was unparseable." };
+    }
+    const resolvedInfo = { ...info, issuedAt: _nullishCoalesce(info.issuedAt, () => ( (/* @__PURE__ */ new Date()).toISOString())) };
+    const message = formatSiweMessage(resolvedInfo, signer.address);
+    const signature = await signer.signMessage(message);
+    const header = encodeBase642(
+      JSON.stringify({ ...resolvedInfo, address: signer.address, type: "eip191", message, signature })
+    );
+    const res = await fetch(X402SCAN_REGISTER, {
+      method: "POST",
+      headers: clientHeaders({
+        "content-type": "application/json",
+        accept: "application/json",
+        "sign-in-with-x": header
+      }),
+      body: JSON.stringify({ url: input.url })
+    });
+    if (res.ok) {
+      return { source: "x402scan", ok: true, status: res.status, detail: "Listed on x402scan (SIWX)." };
+    }
+    const why = await readIndexError(res);
+    return {
+      source: "x402scan",
+      ok: false,
+      status: res.status,
+      detail: why ? `x402scan rejected it (HTTP ${res.status}): ${why}` : `x402scan returned HTTP ${res.status} after signing.`
+    };
+  } catch (err) {
+    return { source: "x402scan", ok: false, detail: errMsg(err) };
+  }
+}
+async function readSiwxInfo(res) {
+  try {
+    const body = await res.json();
+    const ext = body.extensions;
+    const siwx = _optionalChain([ext, 'optionalAccess', _2 => _2["sign-in-with-x"]]);
+    const info = _nullishCoalesce(_optionalChain([siwx, 'optionalAccess', _3 => _3.info]), () => ( siwx));
+    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;
+    }
+    return null;
+  } catch (e14) {
+    return null;
+  }
+}
+function formatSiweMessage(info, address) {
+  const chainId = info.chainId ? caip2ToChainId(info.chainId) : 1;
+  const statement = info.statement && info.statement.trim() ? info.statement : void 0;
+  const lines = [
+    `${info.domain} wants you to sign in with your Ethereum account:`,
+    address,
+    "",
+    ...statement ? [statement, ""] : [""],
+    `URI: ${info.uri}`,
+    "Version: 1",
+    `Chain ID: ${chainId}`,
+    `Nonce: ${info.nonce}`,
+    `Issued At: ${info.issuedAt}`,
+    ...info.expirationTime ? [`Expiration Time: ${info.expirationTime}`] : []
+  ];
+  return lines.join("\n");
+}
+function caip2ToChainId(caip2) {
+  const m = /^eip155:(\d+)$/.exec(caip2);
+  const n = m ? Number(m[1]) : Number(caip2);
+  return Number.isSafeInteger(n) && n > 0 ? n : 1;
+}
+function mapRails(accepts) {
+  if (!Array.isArray(accepts)) return [];
+  const out = [];
+  for (const raw of accepts) {
+    if (!raw || typeof raw !== "object") continue;
+    const a = raw;
+    const network = pickString(a, "network");
+    if (!network) continue;
+    const extra = a.extra && typeof a.extra === "object" ? a.extra : {};
+    out.push({
+      scheme: _nullishCoalesce(pickString(a, "scheme"), () => ( "exact")),
+      network,
+      ...optionalString("asset", pickString(a, "asset")),
+      ...optionalString("amount", pickString(a, "amount", "maxAmountRequired")),
+      ...optionalString("payTo", pickString(a, "payTo")),
+      ...optionalString("symbol", pickString(extra, "symbol"))
+    });
+  }
+  return out;
+}
+function matchesQuery(r, query) {
+  const q = query.toLowerCase();
+  return r.resource.toLowerCase().includes(q) || (_nullishCoalesce(_optionalChain([r, 'access', _4 => _4.name, 'optionalAccess', _5 => _5.toLowerCase, 'call', _6 => _6(), 'access', _7 => _7.includes, 'call', _8 => _8(q)]), () => ( false))) || (_nullishCoalesce(_optionalChain([r, 'access', _9 => _9.description, 'optionalAccess', _10 => _10.toLowerCase, 'call', _11 => _11(), 'access', _12 => _12.includes, 'call', _13 => _13(q)]), () => ( false)));
+}
+function pickString(o, ...keys) {
+  for (const k of keys) {
+    const v = o[k];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return void 0;
+}
+function pickNumber(o, ...keys) {
+  for (const k of keys) {
+    const v = o[k];
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+    if (typeof v === "string" && /^\d+(\.\d+)?$/.test(v.trim())) {
+      const n = Number(v.trim());
+      if (Number.isFinite(n)) return n;
+    }
+  }
+  return void 0;
+}
+function optionalString(field, value) {
+  return value !== void 0 ? { [field]: value } : {};
+}
+function firstArray(o, ...keys) {
+  for (const k of keys) {
+    if (Array.isArray(o[k])) return o[k];
+  }
+  return Array.isArray(o) ? o : [];
+}
+function hostOf(url) {
+  try {
+    return new URL(url).hostname;
+  } catch (e15) {
+    return url;
+  }
+}
+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");
+  throw new Error("No base64 encoder available in this runtime.");
+}
+
 // src/policy.ts
 var ALLOW = { allowed: true };
 var deny = (reason) => ({ allowed: false, reason });
@@ -981,7 +1320,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', _2 => _2.buckets, 'access', _3 => _3.get, 'call', _4 => _4(keyFor(network, asset)), 'optionalAccess', _5 => _5.total]), () => ( 0n));
+    return _nullishCoalesce(_optionalChain([this, 'access', _14 => _14.buckets, 'access', _15 => _15.get, 'call', _16 => _16(keyFor(network, asset)), 'optionalAccess', _17 => _17.total]), () => ( 0n));
   }
   /** An immutable snapshot of all spend so far. */
   summary() {
@@ -1030,7 +1369,7 @@ var PipRailClient = (_class2 = class {
   safeEmit(event) {
     try {
       this.onEvent(event);
-    } catch (e12) {
+    } catch (e16) {
     }
   }
   /** Auto-mount the chain's driver, resolve the network, and bind the wallet — once. */
@@ -1055,7 +1394,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', _6 => _6.headers]));
+    const headers = new Headers(_optionalChain([init, 'optionalAccess', _18 => _18.headers]));
     let payload;
     if (body === void 0 || body === null) {
       payload = void 0;
@@ -1086,7 +1425,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', _7 => _7.method]), () => ( "GET")) });
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _19 => _19.method]), () => ( "GET")) });
     if (res.status !== 402) return null;
     const { quote } = await this.resolveChallenge(url, res);
     return quote;
@@ -1105,7 +1444,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', _8 => _8.method]), () => ( "GET")) });
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _20 => _20.method]), () => ( "GET")) });
     if (res.status !== 402) return null;
     const { net, accept, quote } = await this.resolveChallenge(url, res);
     const cost = await net.estimateCost(accept);
@@ -1136,7 +1475,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', _9 => _9.method]), () => ( "GET")) });
+    const res = await fetch(url, { ..._nullishCoalesce(init, () => ( {})), method: _nullishCoalesce(_optionalChain([init, 'optionalAccess', _21 => _21.method]), () => ( "GET")) });
     if (res.status !== 402) return null;
     const challenge = await parseChallenge(res);
     if (!challenge) {
@@ -1154,6 +1493,100 @@ var PipRailClient = (_class2 = class {
     const plan = await this.planPayment(url, init);
     return plan == null ? true : plan.payable;
   }
+  /* ------------------------- discovery (find + list) ------------------------- */
+  /**
+   * Find payable resources on the OPEN x402 indexes — WITHOUT paying. Reads the
+   * free indexes (CDP Bazaar + 402 Index by default), merges + dedupes them, and
+   * by default returns only resources payable on THIS client's chain
+   * (`network: 'self'`). Each result carries its advertised `rails[]`; feed a
+   * chosen `resource` straight into `quote()` → `planPayment()` → `fetch()`.
+   *
+   * Nothing PipRail-hosted: these are third-party open directories. Never throws
+   * for a read problem — an index that's down or changed simply contributes
+   * nothing. Honest caveat: index results are cross-scheme (mostly the
+   * mainstream `exact` scheme); `fetch()` pays only `onchain-proof` rails
+   * directly (pay `exact` resources with the experimental `drivers/evm/exact.ts`).
+   */
+  async discover(opts = {}) {
+    const found = await searchOpenIndexes({
+      ...opts.query !== void 0 ? { query: opts.query } : {},
+      ...opts.sources ? { sources: opts.sources } : {},
+      ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+    });
+    const scope = _nullishCoalesce(opts.network, () => ( "self"));
+    let out = found;
+    if (scope === "self") {
+      const { net } = await this.ensure();
+      out = out.filter((r) => r.rails.some((rail) => railOnNetwork(rail, (n) => net.supports(n))));
+    } else if (scope !== "any") {
+      const target = normalizeNetwork(scope);
+      out = out.filter((r) => r.rails.some((rail) => railOnNetwork(rail, (n) => n === target)));
+    }
+    if (opts.maxPrice !== void 0) {
+      const max = opts.maxPrice;
+      out = out.filter((r) => r.priceUsd === void 0 || r.priceUsd <= max);
+    }
+    return out;
+  }
+  /**
+   * List a resource you run on the OPEN x402 registries, so agents can find it.
+   * Default target is **402 Index** — one POST, no auth, no signature, no payment
+   * (searchable within seconds). Add `'x402scan'` to also register via SIWX (one
+   * wallet signature; EVM + a Base/Solana rail). Returns one {@link RegisterOutcome}
+   * per target — a target the chain can't satisfy comes back `{ ok:false, detail }`,
+   * never a throw. An explicit, developer-invoked action; it moves no funds, and
+   * nothing is PipRail-hosted — you're listing on third-party open directories.
+   */
+  async register(url, opts = {}) {
+    const targets = _nullishCoalesce(opts.targets, () => ( ["402index"]));
+    const networkSlug = _nullishCoalesce(opts.network, () => ( (typeof this.opts.chain === "string" ? this.opts.chain : void 0)));
+    const outcomes = [];
+    for (const target of targets) {
+      if (target === "402index") {
+        outcomes.push(
+          await register402Index({
+            url,
+            ...opts.name ? { name: opts.name } : {},
+            ...opts.description ? { description: opts.description } : {},
+            ...opts.priceUsd !== void 0 ? { priceUsd: opts.priceUsd } : {},
+            ...opts.asset ? { asset: opts.asset } : {},
+            ...networkSlug ? { network: networkSlug } : {},
+            ...opts.method ? { method: opts.method } : {},
+            ...opts.attribution ? { attribution: true } : {}
+          })
+        );
+      } else if (target === "x402scan") {
+        const signer = await this.discoverySigner();
+        if (!signer) {
+          outcomes.push({
+            source: "x402scan",
+            ok: false,
+            detail: "x402scan registration needs an EVM signer; this chain family has no discoverySigner. Use 402 Index (the default), which needs no signature."
+          });
+          continue;
+        }
+        outcomes.push(await registerX402Scan({ url }, signer));
+      } else {
+        outcomes.push({
+          source: "bazaar",
+          ok: false,
+          detail: "CDP Bazaar has no register endpoint \u2014 it catalogs a resource only when its facilitator settles a payment (PipRail uses no facilitator). List on 402 Index / x402scan instead."
+        });
+      }
+    }
+    return outcomes;
+  }
+  /**
+   * The discovery signer for the bound wallet (its address + a message signer),
+   * or `null` if the chain family doesn't support it (EVM does today). For
+   * discovery only — ownership proofs (sign the bare origin string and pass it to
+   * `buildOpenApi({ ownershipProofs })`) and SIWX registration. Never signs a
+   * payment.
+   */
+  async discoverySigner() {
+    const { net, wallet } = await this.ensure();
+    return net.discoverySigner ? net.discoverySigner(wallet) : null;
+  }
   /**
    * Lower-level: drive any HTTP method through the 402 flow.
    *
@@ -1162,7 +1595,7 @@ var PipRailClient = (_class2 = class {
    * streams throw `NonReplayableBodyError`.
    */
   async fetch(url, init) {
-    const body = _optionalChain([init, 'optionalAccess', _10 => _10.body]);
+    const body = _optionalChain([init, 'optionalAccess', _22 => _22.body]);
     if (body !== void 0 && body !== null && !isReplayableBodyInit(body)) {
       throw new (0, _chunkIQGT65WScjs.NonReplayableBodyError)(
         "fetch(): init.body is not replayable. Pass a string, FormData, URLSearchParams, ArrayBuffer, or Blob \u2014 not a ReadableStream."
@@ -1174,7 +1607,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', _11 => _11.autoRoute]), () => ( this.opts.autoRoute)), () => ( false));
+    const autoRoute = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'optionalAccess', _23 => _23.autoRoute]), () => ( this.opts.autoRoute)), () => ( false));
     if (autoRoute) {
       const plan = await this.planFromChallenge(net, wallet, challenge, url);
       if (!plan.best) {
@@ -1333,11 +1766,11 @@ var PipRailClient = (_class2 = class {
     }
     const amountBase = BigInt(accept.amount);
     const described = net.describeAsset(accept.asset);
-    const decimals = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _12 => _12.decimals]), () => ( accept.extra.decimals));
-    const symbol = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _13 => _13.symbol]), () => ( accept.extra.symbol));
+    const decimals = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _24 => _24.decimals]), () => ( accept.extra.decimals));
+    const symbol = _nullishCoalesce(_optionalChain([described, 'optionalAccess', _25 => _25.symbol]), () => ( accept.extra.symbol));
     const amountFormatted = _chunkIQGT65WScjs.formatUnits.call(void 0, amountBase, decimals);
     const intent = {
-      host: hostOf(url),
+      host: hostOf2(url),
       chain: this.opts.chain,
       network: accept.network,
       asset: accept.asset,
@@ -1400,7 +1833,7 @@ var PipRailClient = (_class2 = class {
     this.ledger.record(
       {
         url: quote.url,
-        host: hostOf(quote.url),
+        host: hostOf2(quote.url),
         network: quote.network,
         asset: quote.asset,
         amountBase: quote.amount,
@@ -1443,7 +1876,7 @@ var PipRailClient = (_class2 = class {
       accepted: accept,
       payload: { nonce: accept.extra.nonce, txHash: ref }
     };
-    const headers = new Headers(_optionalChain([originalInit, 'optionalAccess', _14 => _14.headers]));
+    const headers = new Headers(_optionalChain([originalInit, 'optionalAccess', _26 => _26.headers]));
     headers.set(HEADER_SIGNATURE, buildSignatureHeader(signature));
     let lastResponse = null;
     let lastReason = null;
@@ -1458,7 +1891,7 @@ var PipRailClient = (_class2 = class {
         () => timeoutController.abort(),
         this.retryTimeoutMs
       );
-      const signal = _optionalChain([originalInit, 'optionalAccess', _15 => _15.signal]) && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, originalInit.signal]) : timeoutController.signal;
+      const signal = _optionalChain([originalInit, 'optionalAccess', _27 => _27.signal]) && typeof AbortSignal.any === "function" ? AbortSignal.any([timeoutController.signal, originalInit.signal]) : timeoutController.signal;
       try {
         lastResponse = await fetch(url, {
           ..._nullishCoalesce(originalInit, () => ( {})),
@@ -1498,7 +1931,7 @@ var PipRailClient = (_class2 = class {
 function safeBig(s) {
   try {
     return BigInt(s);
-  } catch (e13) {
+  } catch (e17) {
     return 0n;
   }
 }
@@ -1531,10 +1964,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', _16 => _16.shortfall, 'optionalAccess', _17 => _17.token])) {
+  if (target.blockers.includes("INSUFFICIENT_TOKEN") && _optionalChain([target, 'access', _28 => _28.shortfall, 'optionalAccess', _29 => _29.token])) {
     parts.push(`top up ${target.shortfall.token} ${sym}`);
   }
-  if (target.blockers.includes("INSUFFICIENT_GAS") && _optionalChain([target, 'access', _18 => _18.shortfall, 'optionalAccess', _19 => _19.native])) {
+  if (target.blockers.includes("INSUFFICIENT_GAS") && _optionalChain([target, 'access', _30 => _30.shortfall, 'optionalAccess', _31 => _31.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}.`;
@@ -1548,7 +1981,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', _20 => _20.accept, 'access', _21 => _21.network]), () => ( live[0].network)),
+    network: _nullishCoalesce(_optionalChain([best, 'optionalAccess', _32 => _32.accept, 'access', _33 => _33.network]), () => ( live[0].network)),
     status,
     payable: best !== null,
     best,
@@ -1557,10 +1990,14 @@ async function planAcross(clients, url, init) {
     fundingHint: best ? null : _nullishCoalesce(live.map((p) => p.fundingHint).find(Boolean), () => ( null))
   };
 }
-function hostOf(url) {
+function railOnNetwork(rail, matches) {
+  const n = normalizeNetwork(rail.network);
+  return !n.includes(":") || matches(n);
+}
+function hostOf2(url) {
   try {
     return new URL(url).hostname;
-  } catch (e14) {
+  } catch (e18) {
     return url;
   }
 }
@@ -1583,7 +2020,7 @@ async function readInvalidReason(response) {
         detail: typeof body.detail === "string" ? body.detail : ""
       };
     }
-  } catch (e15) {
+  } catch (e19) {
   }
   return null;
 }
@@ -1594,15 +2031,65 @@ async function readBody(res) {
   if (!text) return null;
   try {
     return JSON.parse(text);
-  } catch (e16) {
+  } catch (e20) {
     return text;
   }
 }
 function paymentTools(client) {
   return [
+    {
+      name: "piprail_discover",
+      description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
+      annotations: {
+        title: "Discover payable x402 APIs",
+        readOnlyHint: true,
+        // reads the open indexes only; never pays
+        openWorldHint: true
+        // reaches external indexes (402 Index, CDP Bazaar)
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Free-text topic to search for (optional)." },
+          network: {
+            type: "string",
+            description: "CAIP-2 id, 'self' (your chain \u2014 default), or 'any' (all chains)."
+          },
+          maxPrice: { type: "number", description: "Drop results advertised above this USD price." },
+          limit: { type: "number", description: "Max results per index (default 20)." }
+        },
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const opts = {};
+        if (typeof args.query === "string") opts.query = args.query;
+        if (typeof args.network === "string") opts.network = args.network;
+        if (typeof args.maxPrice === "number") opts.maxPrice = args.maxPrice;
+        if (typeof args.limit === "number") opts.limit = args.limit;
+        const found = await client.discover(opts);
+        return {
+          count: found.length,
+          resources: found.map((r) => ({
+            resource: r.resource,
+            name: r.name,
+            description: r.description,
+            source: r.source,
+            priceUsd: r.priceUsd,
+            networks: [...new Set(r.rails.map((rail) => rail.network))]
+          }))
+        };
+      }
+    },
     {
       name: "piprail_quote_payment",
       description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
+      annotations: {
+        title: "Quote an x402 price",
+        readOnlyHint: true,
+        // reads the 402 challenge; never pays
+        openWorldHint: true
+        // fetches an arbitrary URL
+      },
       parameters: {
         type: "object",
         properties: {
@@ -1619,6 +2106,13 @@ function paymentTools(client) {
     {
       name: "piprail_plan_payment",
       description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      annotations: {
+        title: "Plan an x402 payment",
+        readOnlyHint: true,
+        // reads balances + the challenge; never pays
+        openWorldHint: true
+        // fetches a URL and reads chain state
+      },
       parameters: {
         type: "object",
         properties: {
@@ -1657,6 +2151,17 @@ function paymentTools(client) {
     {
       name: "piprail_pay_request",
       description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      annotations: {
+        title: "Pay an x402 request",
+        readOnlyHint: false,
+        // this is the one tool that MOVES FUNDS
+        destructiveHint: true,
+        // an on-chain payment is value-moving and not reversible
+        idempotentHint: false,
+        // paying twice = two payments
+        openWorldHint: true
+        // fetches a URL and settles on-chain
+      },
       parameters: {
         type: "object",
         properties: {
@@ -1703,6 +2208,39 @@ function paymentTools(client) {
           throw err;
         }
       }
+    },
+    {
+      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; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      annotations: {
+        title: "Register an x402 endpoint",
+        readOnlyHint: false,
+        // writes a listing to an external index
+        destructiveHint: false,
+        // adds a listing; nothing is destroyed and no funds move
+        openWorldHint: true
+        // posts to external indexes (402 Index)
+        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
+      },
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full URL of the resource to list." },
+          name: { type: "string", description: "Display name (defaults to the host)." },
+          description: { type: "string", description: "What the resource offers." },
+          priceUsd: { type: "number", description: "Advertised price in USD (metadata)." }
+        },
+        required: ["url"],
+        additionalProperties: false
+      },
+      invoke: async (args) => {
+        const opts = {};
+        if (typeof args.name === "string") opts.name = args.name;
+        if (typeof args.description === "string") opts.description = args.description;
+        if (typeof args.priceUsd === "number") opts.priceUsd = args.priceUsd;
+        const outcomes = await client.register(String(args.url), opts);
+        return { outcomes };
+      }
     }
   ];
 }
@@ -1805,6 +2343,25 @@ function createPaymentGate(options) {
     const { challenge: c, requiredHeader } = await challenge();
     return { kind: "challenge", challenge: c, requiredHeader, statusCode: 402 };
   }
+  async function describe(resourceUrl = "") {
+    const specs = await ready();
+    const accepts = specs.map((s) => ({
+      scheme: "onchain-proof",
+      network: s.net.network,
+      asset: s.asset,
+      payTo: s.payTo,
+      amount: s.amountBase.toString(),
+      amountFormatted: s.amountFormatted,
+      decimals: s.decimals,
+      maxTimeoutSeconds,
+      ...s.symbol ? { symbol: s.symbol } : {}
+    }));
+    return {
+      url: resourceUrl,
+      ...options.description ? { description: options.description } : {},
+      accepts
+    };
+  }
   async function verify(paymentSignature) {
     const raw = normaliseHeader(paymentSignature);
     if (!raw) return asChallenge();
@@ -1847,7 +2404,7 @@ function createPaymentGate(options) {
     if (options.onPaid) {
       try {
         options.onPaid(result.receipt);
-      } catch (e17) {
+      } catch (e21) {
       }
     }
     return {
@@ -1856,7 +2413,7 @@ function createPaymentGate(options) {
       receiptHeader: buildReceiptHeader(result.receipt)
     };
   }
-  return { challenge, verify };
+  return { challenge, verify, describe };
 }
 function requirePayment(options) {
   const gate = createPaymentGate(options);
@@ -1954,8 +2511,8 @@ async function buildExactAuthorization(params) {
   };
   const signature = await account.signTypedData({
     domain: {
-      name: _nullishCoalesce(_optionalChain([accept, 'access', _22 => _22.extra, 'optionalAccess', _23 => _23.name]), () => ( "USD Coin")),
-      version: _nullishCoalesce(_optionalChain([accept, 'access', _24 => _24.extra, 'optionalAccess', _25 => _25.version]), () => ( "2")),
+      name: _nullishCoalesce(_optionalChain([accept, 'access', _34 => _34.extra, 'optionalAccess', _35 => _35.name]), () => ( "USD Coin")),
+      version: _nullishCoalesce(_optionalChain([accept, 'access', _36 => _36.extra, 'optionalAccess', _37 => _37.version]), () => ( "2")),
       chainId,
       verifyingContract: accept.asset
     },
@@ -1987,6 +2544,69 @@ function encodeXPaymentHeader(input) {
   return base64(JSON.stringify(payload));
 }
 
+// src/discovery.ts
+var GENERATOR = "@piprail/sdk \xB7 https://piprail.com";
+function pathOf(url) {
+  try {
+    return new URL(url).pathname || "/";
+  } catch (e22) {
+    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}`
+  };
+}
+
+
+
+
+
+
+
+
+
 
 
 
@@ -2026,4 +2646,4 @@ function encodeXPaymentHeader(input) {
 
 
 
-exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkIQGT65WScjs.ConfirmationTimeoutError; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.InsufficientFundsError = _chunkIQGT65WScjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkIQGT65WScjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkIQGT65WScjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkIQGT65WScjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkIQGT65WScjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkIQGT65WScjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkIQGT65WScjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkIQGT65WScjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkIQGT65WScjs.PipRailError; exports.RecipientNotReadyError = _chunkIQGT65WScjs.RecipientNotReadyError; exports.UnknownTokenError = _chunkIQGT65WScjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkIQGT65WScjs.UnsupportedNetworkError; exports.WrongChainError = _chunkIQGT65WScjs.WrongChainError; exports.WrongFamilyError = _chunkIQGT65WScjs.WrongFamilyError; exports.buildChallengeHeader = buildChallengeHeader; exports.buildExactAuthorization = buildExactAuthorization; exports.buildReceiptHeader = buildReceiptHeader; exports.buildSignatureHeader = buildSignatureHeader; exports.chainIdForExactNetwork = chainIdForExactNetwork; exports.createPaymentGate = createPaymentGate; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.parseChallenge = parseChallenge; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.registerDriver = registerDriver; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.toInsufficientFundsError = _chunkIQGT65WScjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody;
+exports.CHAINS = CHAINS; exports.ConfirmationTimeoutError = _chunkIQGT65WScjs.ConfirmationTimeoutError; exports.EIP3009_TYPES = EIP3009_TYPES; exports.EXACT_NETWORK_SLUGS = EXACT_NETWORK_SLUGS; exports.GENERATOR = GENERATOR; exports.InsufficientFundsError = _chunkIQGT65WScjs.InsufficientFundsError; exports.InvalidEnvelopeError = _chunkIQGT65WScjs.InvalidEnvelopeError; exports.MaxRetriesExceededError = _chunkIQGT65WScjs.MaxRetriesExceededError; exports.MissingDriverError = _chunkIQGT65WScjs.MissingDriverError; exports.NoCompatibleAcceptError = _chunkIQGT65WScjs.NoCompatibleAcceptError; exports.NonReplayableBodyError = _chunkIQGT65WScjs.NonReplayableBodyError; exports.PaymentDeclinedError = _chunkIQGT65WScjs.PaymentDeclinedError; exports.PaymentTimeoutError = _chunkIQGT65WScjs.PaymentTimeoutError; exports.PipRailClient = PipRailClient; exports.PipRailError = _chunkIQGT65WScjs.PipRailError; exports.RecipientNotReadyError = _chunkIQGT65WScjs.RecipientNotReadyError; exports.UnknownTokenError = _chunkIQGT65WScjs.UnknownTokenError; exports.UnsupportedNetworkError = _chunkIQGT65WScjs.UnsupportedNetworkError; exports.WrongChainError = _chunkIQGT65WScjs.WrongChainError; exports.WrongFamilyError = _chunkIQGT65WScjs.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.createPaymentGate = createPaymentGate; exports.encodeXPaymentHeader = encodeXPaymentHeader; exports.evaluatePolicy = evaluatePolicy; exports.normalizeNetwork = normalizeNetwork; exports.parseChallenge = parseChallenge; exports.parseExactRequirements = parseExactRequirements; exports.parseReceipt = parseReceipt; exports.parseSignatureHeader = parseSignatureHeader; exports.paymentTools = paymentTools; exports.pickAccept = pickAccept; exports.planAcross = planAcross; exports.register402Index = register402Index; exports.registerDriver = registerDriver; exports.registerX402Scan = registerX402Scan; exports.requirePayment = requirePayment; exports.resolveChain = resolveChain; exports.searchOpenIndexes = searchOpenIndexes; exports.toInsufficientFundsError = _chunkIQGT65WScjs.toInsufficientFundsError; exports.toInvalidBody = toInvalidBody;