@piprail/sdk 1.6.0 → 1.8.0

package/dist/index.js

@@ -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 SLUG_TO_CAIP2[network.toLowerCase()] ?? network;
+}
+async function searchOpenIndexes(opts = {}) {
+  const sources = opts.sources ?? ["bazaar", "402index"];
+  const limit = 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 {
+    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", 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 = (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: network ?? "unknown",
+      ...asset ? { asset } : {},
+      ...optionalString("symbol", asset)
+    }
+  ];
+}
+async function register402Index(input) {
+  try {
+    const payload = {
+      url: input.url,
+      name: 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 {
+    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: 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 = ext?.["sign-in-with-x"];
+    const info = siwx?.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 {
+    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: 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) || (r.name?.toLowerCase().includes(q) ?? false) || (r.description?.toLowerCase().includes(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 {
+    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 });
@@ -1154,6 +1493,100 @@ var PipRailClient = 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 = 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 = opts.targets ?? ["402index"];
+    const networkSlug = 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.
    *
@@ -1337,7 +1770,7 @@ var PipRailClient = class {
     const symbol = described?.symbol ?? accept.extra.symbol;
     const amountFormatted = formatUnits(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 = class {
     this.ledger.record(
       {
         url: quote.url,
-        host: hostOf(quote.url),
+        host: hostOf2(quote.url),
         network: quote.network,
         asset: quote.asset,
         amountBase: quote.amount,
@@ -1557,7 +1990,11 @@ async function planAcross(clients, url, init) {
     fundingHint: best ? null : 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 {
@@ -1600,9 +2037,59 @@ async function readBody(res) {
 }
 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();
@@ -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);
@@ -1986,11 +2543,67 @@ 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 {
+    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,
   EIP3009_TYPES,
   EXACT_NETWORK_SLUGS,
+  GENERATOR,
   InsufficientFundsError,
   InvalidEnvelopeError,
   MaxRetriesExceededError,
@@ -2008,12 +2621,16 @@ export {
   WrongFamilyError,
   buildChallengeHeader,
   buildExactAuthorization,
+  buildOpenApi,
   buildReceiptHeader,
   buildSignatureHeader,
+  buildWellKnownX402,
+  buildX402DnsTxt,
   chainIdForExactNetwork,
   createPaymentGate,
   encodeXPaymentHeader,
   evaluatePolicy,
+  normalizeNetwork,
   parseChallenge,
   parseExactRequirements,
   parseReceipt,
@@ -2021,9 +2638,12 @@ export {
   paymentTools,
   pickAccept,
   planAcross,
+  register402Index,
   registerDriver,
+  registerX402Scan,
   requirePayment,
   resolveChain,
+  searchOpenIndexes,
   toInsufficientFundsError,
   toInvalidBody
 };